--- id: SVC-PFM-INT-extensions title: Customization registry and configuration service product_area: platform module: integrations revision: 1 status: draft repository: services-platform source_module: modules/extensions design_intent: proposed implementation_evidence: partially-observed inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-PFM-INT-005 does_not_own: - >- Host applications define the business meaning of points, resolve handlers and write invocation outcomes through restricted roles. - The query service supplies read-only record facts for rule evaluation. - Security controls grants and owns security audit storage. - The integrations service delivers external business-event subscriptions. operations: - operation_id: getExtensionsHealth intent: Return deployment health for the customization API. access: public permission: 'none: public health route' realises: [] published_to_submissions: 'not published: deployment health, not a business operation' - operation_id: listExtensionPoints intent: 'Browse registered points, available versions and local binding totals.' access: console permission: platform.extension-points.read realises: - CAP-PFM-INT-016 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: getExtensionPoint intent: 'Inspect a point’s contracts, examples, declared facts and binding totals.' access: console permission: platform.extension-points.read realises: - CAP-PFM-INT-016 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: listEventTypes intent: Browse business event declarations and their payload schemas. access: console permission: platform.extension-points.read realises: - CAP-PFM-INT-016 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: getEventType intent: Inspect the versioned contract of one business event. access: console permission: platform.extension-points.read realises: - CAP-PFM-INT-016 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: listExtensionHandlers intent: Browse named handlers configured for this workspace. access: console permission: platform.extension-points.read realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: createExtensionHandler intent: >- Create a Lambda, built-in or rule handler; HTTPS handlers remain unavailable pending the existing product decision. access: console permission: >- Route permission metadata: platform.extension-points.read; anyOf: platform.extension-handlers.manage, platform.extension-rules.manage. The handler additionally requires the manage key for its kind. realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: configuration or operational administration by staff, not an intake capture' - operation_id: getExtensionHandler intent: Inspect handler settings without returning secret values. access: console permission: platform.extension-points.read realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: updateExtensionHandler intent: Edit a handler using the record version previously read. access: console permission: >- Route permission metadata: platform.extension-points.read; anyOf: platform.extension-handlers.manage, platform.extension-rules.manage. The handler additionally requires the manage key for its kind. realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: configuration or operational administration by staff, not an intake capture' - operation_id: deleteExtensionHandler intent: Remove an unreferenced handler and request recoverable deletion of its secret. access: console permission: >- Route permission metadata: platform.extension-points.read; anyOf: platform.extension-handlers.manage, platform.extension-rules.manage. The handler additionally requires the manage key for its kind. realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: configuration or operational administration by staff, not an intake capture' - operation_id: testExtensionHandler intent: Exercise a handler with supplied input or a declared example. access: console permission: platform.extension-handlers.test realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: configuration or operational administration by staff, not an intake capture' - operation_id: listExtensionBindings intent: 'Browse bindings, narrowing the results by point, handler or standing.' access: console permission: platform.extension-points.read realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: createExtensionBinding intent: Assign a handler to a point within a selected scope. access: console permission: platform.extension-bindings.manage realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: configuration or operational administration by staff, not an intake capture' - operation_id: previewExtensionResolution intent: 'Explain the selected binding, or the ordered set for a multiple-handler point.' access: console permission: platform.extension-points.read realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: updateExtensionBinding intent: Edit a binding using its previously read version. access: console permission: platform.extension-bindings.manage realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: configuration or operational administration by staff, not an intake capture' - operation_id: deleteExtensionBinding intent: Remove a binding from its point and scope. access: console permission: platform.extension-bindings.manage realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: configuration or operational administration by staff, not an intake capture' - operation_id: listExtensionInvocations intent: 'Browse recent invocations with point, handler, outcome, purpose and time filters.' access: console permission: platform.extension-invocations.read realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: getExtensionInvocation intent: Inspect an invocation and the payload references retained under its capture settings. access: console permission: platform.extension-invocations.read realises: - CAP-PFM-INT-017 published_to_submissions: 'not published: a read or explanation, not a capture' - operation_id: registerServiceExtensions intent: >- Replace one application’s point, event and subscriber declarations during deployment, retiring omitted entries. access: internal permission: >- none: invoked over IAM by a deploy role holding the registration invoke policy; the declared service name is not compared with the caller realises: - CAP-PFM-INT-016 published_to_submissions: 'not published: deploy-time registration by code, not a capture' events: - name: Extension registration fragment direction: consumed when: Deployment submits a complete application customization declaration. payload_summary: 'Application ownership, manifest revision, point contracts, event declarations and native subscribers.' - name: Extension invocation records direction: consumed when: A host uses its restricted writer role to save invocation history. payload_summary: 'Selected point contract, handler and binding, purpose, result, timestamps and diagnostic outcome.' jobs: [] integrations: - system: AWS Secrets Manager direction: outbound contract: >- Secrets can be created, replaced or scheduled for deletion under the workspace prefix; the service cannot retrieve their values. - system: Platform query layer direction: outbound contract: Rule fact checks use read-only eligibility evaluation within the caller’s workspace and person context. consistency: - rule: >- An application’s registry replacement and the resulting binding orphaning either commit together or leave the prior declaration intact. kind: transactional compensation: Refused registrations retain the earlier registry. - rule: >- Handler and binding database mutations include their security audit writes; external secret calls cannot be rolled back with those writes. kind: transactional compensation: >- A successful secret mutation can outlive a failed database commit. Deletion requests allow seven days of recovery. - rule: Hosts observe a configuration edit when they next resolve the point. kind: eventual compensation: No background correction is provided. evidence: - >- services-platform at ad3f6a65: modules/extensions/aws/api/extensions.routes.ts; aws/lambda/REGISTRATION.handler.ts; services/**; lifecycle.ts; resolution.ts; aws/platform.service.ts (extension keys) - >- services-platform at ad3f6a65: docs/extensions.md; docs/proposals/extensibility/decision-log.md (A2, A4, A7) - 'react-console at baf6dae3: lib/extensions/adapters.ts (the console reads sample data, not this service)' controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Customization registry and configuration service ## What the Service Owns This service keeps customization declarations, reusable handlers and scoped bindings. Hosts resolve and invoke those bindings through the shared library; their invocation-writer role permits recording outcomes without transferring ownership of business records. ## Operations The operation rows define the callable boundary, its access class, exact permission declarations and planning coverage. Configuration and operational administration are not published as intake captures. Public health and provider callbacks retain their declared access boundaries. ## Consistency and Failure An application’s registry replacement and the resulting binding orphaning either commit together or leave the prior declaration intact. Refused registrations retain the earlier registry. Handler and binding database mutations include their security audit writes; external secret calls cannot be rolled back with those writes. A successful secret mutation can outlive a failed database commit. Deletion requests allow seven days of recovery. Hosts observe a configuration edit when they next resolve the point. No background correction is provided. ## Events and Jobs The declarations distinguish application events, incoming requests, queue work and direct host reads. These are different transport boundaries; registering a declaration does not by itself publish an application event. ## Open Questions Secret storage is outside database rollback. The console contracts describe mock previews, and actual handler testing remains less complete than production invocation. No scoped operation calls a language model.