Skip to main content
Jira progress: loading…

ZAMG-CCIN

ZAMG–CSI/CMI Integration Spec

1. Purpose​

This specification defines how ZAMG resolves, validates, and uses CMI and CSI inside the ZAR framework.

It covers:

  • how artifact identity is resolved from zar.cmi_registry
  • how signal identity is resolved from zar.signal_csi_binding
  • how proposal paths are triggered when canonical matches do not exist
  • how these identities are incorporated into compiled manifests
  • how approval policy should treat CMI/CSI ambiguity
  • how deterministic and AI-assisted resolution should interact

This spec assumes:

  • ZAR is the canonical registry backbone
  • ZAMG is a compiler over ZAR-backed data
  • canonical manifests are stored in zar.artifact_manifest_registry
  • approval evidence and review workflow operate through ZAR-backed tables

2. Core principle​

CMI and CSI are not generated as free-floating strings inside ZAMG. They are resolved from ZAR-native registry structures wherever possible.

That means:

  • CMI authority = zar.cmi_registry
  • CSI authority = zar.signal_csi_binding

If no canonical match exists, ZAMG should produce:

  • a proposal path
  • a review-required candidate
  • or a rejected/quarantined result

It should not silently invent production identities.

3. Canonical identity sources​

3.1. CMI source​

Primary canonical artifact identity source:

  • zar.cmi_registry

Key fields:

  • cmi
  • module_code
  • component_id
  • cmi_kind
  • artifact_name
  • version_major
  • version_minor
  • version_patch
  • version_text
  • zar_code
  • title
  • description
  • semantic_role
  • runtime_class
  • artifact_location
  • implementation_ref
  • owner_team
  • source_doc_id
  • source_file
  • md_document_link
  • status
  • lifecycle_status

3.2. CSI source​

Primary canonical signal identity source:

  • zar.signal_csi_binding

Key fields:

  • signal_id
  • csi_module
  • csi_component
  • csi_kind
  • csi_name
  • csi_version_maj
  • csi_version_min
  • csi
  • status
  • version
  • sort_order
  • csi_proposal_id

4. Integration goals​

ZAMG must be able to:

For CMI

  • identify the correct artifact identity
  • distinguish existing canonical artifacts from new candidates
  • use the correct versioned artifact identity in the compiled manifest
  • avoid accidental duplication or identity drift

For CSI

  • resolve input and output signal contracts
  • prefer approved/stable CSI bindings
  • detect ambiguity when multiple candidate bindings exist
  • produce reviewable candidate contracts where exact signal mapping is not yet settled

5. CMI resolution model​

5.1. Inputs used for CMI resolution​

ZAMG may use:

  • source docs/frontmatter
  • code paths
  • component mappings
  • engine/micro-engine registries
  • documented component registries
  • module registry and aliases
  • explicit CMI references if already present
  • version metadata
  • artifact type and operation context

5.2. CMI resolution order​

ZAMG should resolve CMI in this order:

Step 1 — explicit canonical reference

If source metadata already contains a known valid cmi, validate against zar.cmi_registry.

If found and valid:

  • use it
  • capture resolution mode as registry_lookup

Step 2 — exact identity match

Attempt exact match using:

  • module_code
  • component_id
  • cmi_kind
  • artifact_name
  • version_text

against:

  • zar.cmi_registry

If unique match found:

  • use it
  • capture resolution mode as deterministic + registry_lookup

Step 3 — deterministic candidate derivation

If no exact match:

  • derive candidate values from module/component metadata
  • normalize artifact name to meet registry format
  • derive version from source or default versioning policy
  • construct candidate CMI using registry rules

Then:

  • validate candidate format
  • check for uniqueness collision in zar.cmi_registry

If unique and allowed:

  • route to proposal/review flow

Step 4 — proposal path

If canonical CMI does not exist:

  • insert or enrich candidate in cmi_proposal_results
  • compile manifest in review_required or quarantined_candidate state depending on policy

6. CMI status policy​

ZAMG must not treat all CMI rows equally.

6.1. Production preference​

For production manifest promotion, prefer:

  • status = active
  • lifecycle_status = active

6.2. Allowed in preview/internal modes​

For internal, preview, or staging modes, allow:

  • `draft
  • active`

if policy permits.

6.3. Auto-promotion restrictions​

Do not auto-promote into production if:

  • status = deprecated
  • status = retired
  • lifecycle_status = deprecated
  • lifecycle_status = retired

These should trigger review or rejection depending on context.

7. CMI fields projected into the canonical manifest​

The compiled manifest should not duplicate all CMI columns, but it should project the most important ones.

Required projection fields

  • artifact.cmi
  • artifact.zar_code
  • artifact.readable_name from title/source normalization
  • artifact.artifact_type
  • artifact.owner_team
  • artifact.status

Recommended projected metadata

  • artifact.source_refs
  • artifact.lineage.parent_artifact_cmi
  • selected semantic/runtime metadata where useful

Internal resolution metadata

Even if not exposed in the visible manifest shape, ZAMG should preserve internally:

  • component_id
  • module_code
  • cmi_kind
  • version_text
  • cmi_registry_id if you choose to expose or track it internally later

8. CSI resolution model​

8.1. Core principle​

CSI should be resolved signal-first, not prose-first.

That means ZAMG should try to identify the underlying signal or signal binding source before deciding the final CSI set.

8.2. Inputs used for CSI resolution​

ZAMG may use:

  • explicit signal_id
  • known signal registry references
  • engine/signal bindings
  • component/signal bindings
  • input/output schema field mappings
  • existing documented signal mappings
  • route payload models
  • approved prior manifests for the same artifact family
  • AI suggestions where signal meaning is ambiguous

8.3. CSI resolution order​

Step 1 — explicit signal_id

If source metadata or binding data identifies signal_id:

  • join to zar.signal_csi_binding
  • retrieve candidate CSI rows

Step 2 — binding-assisted signal discovery

If no direct signal_id:

  • resolve through:
    • signal_engine_binding
    • signal_component_binding
    • signal_binding_registry
    • related documented component structures
    • then join to signal_csi_binding

Step 3 — schema-to-signal mapping

If still unresolved:

  • attempt deterministic mapping from schema fields or known signal naming patterns
  • identify likely signal_id
  • then join to signal_csi_binding

Step 4 — AI-assisted signal interpretation

Only if deterministic resolution is insufficient:

  • infer likely signal intent
  • propose likely signal_id or CSI candidates
  • mark as AI-suggested
  • require review for critical fields

Step 5 — proposal path

If no acceptable CSI exists:

  • create or enrich proposal through CSI/signal proposal workflow
  • keep manifest in review_required or quarantined_candidate state depending on risk

9. CSI candidate prioritization​

When multiple CSI rows are available for a given signal, ZAMG should use a deterministic ranking policy.

Recommended status priority

For production use:

  1. stable
  2. experimental
  3. draft
  4. legacy
  5. deprecated
  6. retired

Additional tie-breakers

If multiple rows share acceptable status, rank by:

  1. exact component/module fit
  2. exact kind fit
  3. exact name fit
  4. preferred version
  5. lowest sort_order
  6. latest updated/approved path if you later track that formally

Production auto-approval policy

For production manifests:

  • prefer stable
  • allow experimental only if explicitly policy-approved
  • do not auto-approve draft, deprecated, or retired

10. CSI fields projected into the canonical manifest​

The manifest should primarily emit the assembled CSI strings, because they are the contract-level identifiers.

Required operation-level fields

  • operations[*].input.csi
  • operations[*].output.csi

Recommended internal preservation

ZAMG should keep internally:

  • signal_id
  • csi_module
  • csi_component
  • csi_kind
  • csi_name
  • csi_version_maj
  • csi_version_min
  • status

This is important because:

  • deterministic review is easier with decomposed parts
  • later remapping/version transitions become easier
  • approval evidence becomes more precise

11. Manifest generation behavior for CMI/CSI states​

11.1. Canonical happy path​

When:

  • CMI resolves uniquely to active canonical row
  • CSI resolves uniquely to acceptable canonical bindings
  • no ambiguity exists

Then:

  • compile candidate manifest
  • apply deterministic defaults
  • proceed to approval logic normally

11.2. Mixed certainty path​

When:

  • CMI is canonical
  • CSI is partially ambiguous or AI-suggested

Then:

  • compile manifest
  • flag critical unresolved/review-needed fields
  • send to review queue
  • record field-level resolution provenance

11.3. Proposal path​

When:

  • CMI is missing or
  • critical CSI bindings are missing

Then:

  • compile proposal-assisted manifest candidate
  • set approval_state to review_required or quarantined_candidate
  • link to proposal/result structures where possible
  • prevent canonical production promotion

12. Proposal integration model​

ZAMG should use your existing proposal/result tables rather than invent a separate candidate identity system.

CMI-related proposal structures

  • zar.cmi_proposal_results

CSI-related proposal structures

  • zar.csi_proposal_results
  • potentially signal_proposal_results depending on whether signal identity itself is unresolved

Recommended behavior

  • if candidate identity is new, unresolved, or ambiguous, record proposal row
  • bind proposal refs into resolution_meta or change_control
  • approval process confirms whether proposal becomes canonical registry entry before production promotion

This aligns ZAMG with the broader ZAR governance model.

13. Resolution metadata requirements for CMI/CSI​

Every CMI and CSI field used in a manifest should carry provenance in resolution_meta.

For CMI

At minimum capture:

  • resolution mode
  • source table
  • source key
  • confidence
  • review status

Example:

cmi-resolution-metadata.yamlGitHub ↗
resolution_meta:
  field_resolution:
    artifact.cmi:
      resolution_mode: "registry_lookup"
      source_ref: "zar.cmi_registry:cmi=MICE.InvoiceEmissions.Engine.1_1_0"
      confidence: 1.0
      review_status: "not_required"

For CSI

Example:

csi-resolution-metadata.yamlGitHub ↗
resolution_meta:
  field_resolution:
    operations[0].input.csi:
      resolution_mode: "registry_lookup"
      source_ref: "zar.signal_csi_binding:signal_id=sig_12345"
      confidence: 0.98
      review_status: "not_required"

If AI-assisted:

ai-assisted-resolution-metadata.yamlGitHub ↗
resolution_meta:
  field_resolution:
    operations[0].output.csi:
      resolution_mode: "ai_suggested_human_confirmed"
      source_ref: "zamg-ai-csi-mapper-v0.1"
      confidence: 0.87
      review_status: "confirmed"

14. Approval policy implications for CMI/CSI​

Because CMI and CSI are critical fields, the approval policy must treat them strictly.

CMI review triggers

Always require review when:

  • CMI must be newly allocated
  • CMI collides
  • artifact type conflicts with resolved CMI
  • active CMI is not available for production use
  • a different canonical CMI than expected is selected

CSI review triggers

Always require review when:

  • CSI is AI-suggested for critical input/output contract
  • multiple acceptable CSI candidates exist
  • only draft or experimental candidates exist for production
  • output CSI is missing
  • signal meaning conflicts with candidate CSI family/kind

15. ZAMG query behavior against ZAR​

Recommended query pattern for CMI

ZAMG should:

  • look up exact rows in cmi_registry
  • validate status/lifecycle
  • reuse zar_code if present
  • never generate a new zar_code silently for production use without review

Recommended query pattern for CSI

ZAMG should:

  • resolve through signal relationships first
  • join to signal_csi_binding
  • apply status priority and tie-break rules
  • preserve both assembled csi and decomposed parts internally

Once you are ready, I strongly recommend adding or exposing consistent linkages between:

  • engine_registry
  • micro_engine_registry
  • component_registry
  • signal_engine_binding
  • signal_component_binding
  • documented_component_registry

The stronger those deterministic relationships become, the less AI ZAMG will need for CSI/CMI interpretation.

That will improve:

  • confidence
  • automation rate
  • approval throughput
  • contract consistency

17. Example integration flows​

Example 1 — Existing micro-engine

Input:

  • documented micro-engine page
  • matching component
  • known engine entry
  • existing active CMI
  • known input/output signals with stable CSI

Result:

  • exact CMI resolved
  • input/output CSI resolved
  • manifest compiled from canonical identities
  • likely reviewer-free if other conditions are low-risk

Example 2 — New exporter with partial CSI

Input:

  • new exporter docs and route
  • no exact CMI row yet
  • likely output signal exists but input packaging CSI is ambiguous

Result:

  • CMI proposal path triggered
  • CSI partially AI-suggested
  • review queue entry created
  • manifest stored as review-required candidate
  • no production promotion until identities are confirmed

18. Final rules​

Rule 1

CMI and CSI are resolved from ZAR canonical tables whenever possible.

Rule 2

ZAMG may propose identities, but may not silently promote invented production identities.

Rule 3

CMI and CSI are critical fields and must carry resolution provenance.

Rule 4

Production manifests require stricter status filtering than internal or preview manifests.

Rule 5

Proposal tables should be reused as the staging path for unresolved CMI/CSI.

19. Final conclusion​

This integration model makes ZAMG:

  • ZAR-native
  • deterministic-first
  • proposal-aware
  • approval-aware
  • compatible with future automation


GitHub RepoRequest for Change (RFC)
Tags:
Last updated on by automation-bot