6.iCartridge extended metadata — doctrine

1. Why extended metadata

Every cartridge interacts with five things beyond its own UI: data (what sensitivity tier, what KMS key, what PII handling), retention (how long it keeps what), AI spend (which models, how much), systems of record (which SoRs it can read/write, at what rate), and egress (which destinations its network calls can reach). Each one of these has a doctrinal layer that already exists at the platform level. Without metadata, every cartridge author redecides each question, and the platform can't audit or enforce centrally.

The metadata model says: the cartridge declares what it needs; the platform enforces what it declared. That's the iOS Info.plist + iOS entitlements pattern, applied to vibe apps.

2. v2 manifest shape — full sketch

Nine sections. Sections marked (today) already exist in v0 and stay structurally where they are (just reorganized into the namespaced form below). Sections marked (extended) are the post-60d additions.

{
  // ── Manifest envelope ────────────────────────────────────────
  manifestVersion: 2,
  id:              'chatbot',
  version:         '1.0.0',

  // ── Display (today) ──────────────────────────────────────────
  display: {
    name:        'Chatbot',
    description: 'Claude via Bedrock',
    icon:        'fa-comments',
    color:       'purple',
  },

  // ── Loading (today) ──────────────────────────────────────────
  load: {
    mode:    'iframe',
    url:     'https://chatbot.ai-sandbox.paycargo.com/',
    sandbox: ['allow-scripts','allow-same-origin','allow-forms'],
  },

  // ── Access control (today + extended) ────────────────────────
  access: {
    requiredGroups:   ['chatbot-users'],
    departmentOwner:  'engineering',     // which dept's roster owns this
    audience:         'platform',        // platform / cxo / ciso / dept
  },

  // ── Data governance (extended) ───────────────────────────────
  governance: {
    sensitivityTier: 'internal',         // public / internal / confidential / restricted
    kmsTier:         'eng-low-risk',     // which CMK from the data-governance grid
    piiMode:         'none',             // none / tokenized / lockbox-mediated
    dataResidency:   ['us-east-1'],
  },

  // ── Retention (extended) ─────────────────────────────────────
  retention: {
    sessionTtlDays:  90,
    auditYears:      7,
    archivePolicy:   'glacier-after-1y',
    deletionMode:    'soft-then-purge',
  },

  // ── AI budget (extended) ─────────────────────────────────────
  budget: {
    monthlyCeilingUSD:  500,
    softWarnPct:        0.75,
    hardCapBehavior:    'degrade',       // degrade / disable
    allowedModels: [
      'anthropic.claude-haiku-4-5-*',
      'anthropic.claude-sonnet-4-5-*',
    ],
    defaultGuardrailId: 'gr-xxxxx',
  },

  // ── Systems of Record (extended) ─────────────────────────────
  sor: {
    salesforce: { scope: 'read-only',  rateLimit: '60/min' },
    monday:     { scope: 'read-write', rateLimit: '120/min' },
    github:     { scope: 'read-only',  rateLimit: '5000/hr' },
    gitbook:    { scope: 'read-only',  rateLimit: 'unlimited' },
  },

  // ── Egress allowlist (extended; derived from sor + extras) ───
  egress: {
    destinations: [
      'api.salesforce.com',
      'api.monday.com',
      'api.github.com',
      'api.gitbook.com',
    ],
  },

  // ── Lifecycle + ops (extended) ───────────────────────────────
  lifecycle: {
    status:             'beta',          // alpha / beta / ga / deprecated / sunset
    createdAt:          '2026-06-01',
    lastSecurityReview: '2026-06-01',
    owningTeam:         'eng-platform',
    onCallRotation:     'eng-platform',
  },
}

3. Per-section deep dive

3.1 access — who can see and use this cartridge

Today's requiredGroups is the only access mechanism. v2 keeps that AND adds department ownership (for audit + accounting) and audience (for UI organization). Department determines which CMK tier the cartridge's data is encrypted with; audience just affects which Console section the tile renders in.

3.2 governance — data classification + encryption

piiMode contract

• none — cartridge guarantees it never receives PII (the AI-sandbox pilot constraint). Lint fails if cartridge code includes any of the PII regex patterns.
• tokenized — cartridge receives opaque tokens; the lockbox resolves token→PII via authorized, audited calls. Default mode for any cartridge that touches customer data.
• lockbox-mediated — cartridge is itself the lockbox (rare). Has the unique audit-write CMK, all reveals routed through it.

3.3 retention — how long data lives

3.4 budget — AI spend ceiling

degrade means fall back to a cheaper model (Haiku) once the ceiling is hit; disable means return a "monthly budget exhausted" error to the user. Cartridge declares which behavior it wants based on its UX.

3.5 sor — Systems of Record access scope

Per-SoR access is two dimensions: scope (read-only / read-write / none) and rate limit. The cartridge backend's SoR client library reads this manifest at startup and refuses calls that violate either.

sor: {
  salesforce: { scope: 'read-only',  rateLimit: '60/min' },
  monday:     { scope: 'read-write', rateLimit: '120/min' },
  github:     { scope: 'read-only',  rateLimit: '5000/hr' },
  gitbook:    { scope: 'read-only',  rateLimit: 'unlimited' },
}

Pilot allowlist is exactly four SoRs (Salesforce, Monday, GitHub, GitBook) per the egress doctrine. Adding a fifth requires a platform-level change, not a per-cartridge flag — that's intentional.

3.6 egress — Network Firewall allowlist

Derived from sor for most cartridges (each SoR has known API hostnames). But some cartridges may need additional egress destinations (e.g. a public RSS feed, a static CDN). Listing them here lets the NFW rule generator produce the right allowlist without manual touch.

Default egress posture: deny-all. Each entry in egress.destinations opens one hostname. Sub-pattern matching (*.example.com) allowed but discouraged — list exact hostnames where possible.

3.7 lifecycle — cartridge status + ownership

4. Where each section is enforced

Enforcement is split between the Console (launcher-side) and the cartridge's own backend (runtime-side). Roughly: Console gates discoverability + UI; cartridge backend gates runtime behavior.

5. Versioning

The top-level manifestVersion field exists so the Console can support v1 cartridges (today's 8-field shape) and v2 cartridges (this doc) side-by-side during the migration. The handler reads manifestVersion first and dispatches to the right parser.

• v1 (today): flat fields, no sections. Console treats every section as default.
• v2 (this doc): sectioned shape above. Console enforces what's declared.
• v3+ (future): append-only. Adding a new top-level section is non-breaking; cartridges that don't set it get platform defaults.

Manifest version is per-cartridge, NOT global. A v1 cartridge and a v2 cartridge can live in the same CARTRIDGES array; the launcher renders both correctly.

6. Migration from v1 to v2

1. Add the manifest dispatcher to handler.js. Read manifestVersion; default to 1 for entries that don't set it.
2. Define platform defaults. Each v2 section has a default value (e.g. governance.sensitivityTier: 'internal', retention.sessionTtlDays: 90). A v1 cartridge gets ALL defaults applied silently.
3. Migrate existing cartridges one at a time. Obs (when migrated to cartridge form) becomes v2 with explicit declarations. Chatbot ships as v2 from day one.
4. Lint deploys. CI rejects new cartridges that don't declare every required v2 section.
5. Set a sunset date for v1. Six months after v2 ships, drop the v1 dispatcher. Any cartridge still on v1 must migrate or be archived.

7. Where this metadata lives

Today: hardcoded in handler.js's CARTRIDGES array. Fine for v0 with three entries; not fine when there are 20 cartridges and an Admin tab edits them.

Future iterations (the natural progression):

1. v1.1: move CARTRIDGES to cartridges.json in the same Lambda zip. Easier diff in PR, no logic change.
2. v1.2: move to S3 (s3://ai-sandbox-console-frontend/cartridges.json). Lambda reads at cold start. Admin tab can write without redeploy.
3. v2: move to DynamoDB (one item per cartridge). Admin tab CRUD via API. Each item has the full v2 schema above.
4. v2.1: Bedrock guardrail + KMS key + NFW rules auto-generated from manifest at deploy time. Manifest becomes the single source of truth.

8. Open questions / TODOs

9. Doctrine pins reinforced

• § Declaration vs Discretion. Cartridges declare what they need; the platform enforces what's declared. Anything a cartridge could quietly decide gets moved into the manifest.
• § Sectioned by concern. Nine sections, each owned by a distinct doctrinal layer (data gov, retention, budget, SoR, egress, etc.). Adding a tenth concern post-60d is appending a key, never restructuring.
• § Versioned manifest, append-only. manifestVersion lets v1 and v2 cartridges coexist. v3+ adds sections, never moves existing ones.
• § Platform defaults absorb missing declarations. A v1 cartridge declares 8 fields and inherits sane defaults for the other 7 sections. Migration is incremental; nothing breaks if a cartridge isn't fully migrated.
• § Enforcement is split. Console gates discoverability + UI behavior. Cartridge backend gates runtime behavior. Platform (Terraform + NFW + KMS) gates resource-level rules. Three enforcement points, one source of truth (the manifest).