Jira progress: loading…

OPCODE-RES

ZAMG Opcode Resolution Query Spec

1. Purpose

This specification defines how ZAMG resolves opcode-related fields from ZAR-backed registry tables when generating or validating artifact manifests.

It covers how ZAMG should:

• resolve operation_key -> opcode
• validate artifact type compatibility
• inherit default opcode behavior
• determine whether ZSSR routing is required
• determine whether public API exposure is allowed
• determine policy defaults
• identify review triggers
• attach ruleset profile guidance
• record resolution provenance

This spec assumes the following ZAR tables exist:

• zar.opcode_category_registry
• zar.opcode_registry
• zar.opcode_registry_change_log
• zar.opcode_artifact_type_binding
• zar.opcode_ruleset_profile_binding

---

2. Core principle

Opcode resolution must be deterministic-first, registry-backed, and review-aware.

That means:

1. resolve from operation_key
2. validate against opcode_registry
3. validate artifact type via explicit binding table
4. enrich with ruleset profile recommendations
5. compute review triggers from opcode governance metadata
6. only use AI if the source operation itself is ambiguous before registry resolution

AI should never invent an opcode when a valid registry mapping exists.

---

3. Required registry roles

3.1. zar.opcode_registry

Canonical source of opcode meaning and defaults.

3.2. zar.opcode_artifact_type_binding

Canonical source of allowed opcode-to-artifact-type compatibility.

This replaces or complements JSON arrays in the main registry.

3.3. zar.opcode_ruleset_profile_binding

Canonical source of recommended or required ruleset families by opcode.

3.4. zar.opcode_registry_change_log

Audit and lifecycle trail for opcode changes.

Useful for:

• review triggers
• compatibility awareness
• explaining why an opcode mapping changed

---

4. Resolution inputs

ZAMG opcode resolution starts from some combination of:

• normalized operation_key
• resolved artifact_type
• optional public_api intent
• optional execution context
• optional framework/jurisdiction context
• optional source operation hints

Example inputs

example-inputs.yamlGitHub ↗

operation_key: "export_xbrl"
artifact_type: "exporter"
public_api: true
environment_scope: "production"

---

5. Resolution stages

Stage 1 — Normalize operation key

ZAMG should normalize source operation names into canonical operation_key before querying.

Examples

• runEmissionCalc → compute_metric
• doXbrlExport → export_xbrl
• reviewRequest → request_human_review

This happens before registry lookup.

If no canonical operation key can be derived:

• mark unresolved
• enter review path
• do not query opcode registry blindly by raw source text

---

Stage 2 — Resolve primary opcode row

Primary query

primary-query.sqlGitHub ↗

SELECT
    o.opcode_registry_id,
    o.opcode,
    o.operation_key,
    o.readable_name,
    o.category_code,
    o.subcategory_code,
    o.description,
    o.intent_class,
    o.public_api_allowed,
    o.internal_zcp_required,
    o.requires_zssr,
    o.replay_supported,
    o.idempotency_default,
    o.default_execution_mode,
    o.input_contract_type,
    o.output_contract_type,
    o.default_audit_required,
    o.default_human_review_required,
    o.default_retention_class,
    o.default_trust_threshold,
    o.default_geo_scope,
    o.security_class,
    o.compliance_impact,
    o.ai_usage_allowed,
    o.override_requires_approval,
    o.status,
    o.introduced_in,
    o.deprecated_in,
    o.retired_in
FROM zar.opcode_registry o
WHERE o.operation_key = $1;

Expected result

Exactly one active or draft row.

Failure modes

• no row found
• multiple rows found, which should not happen because operation_key is unique

Rules

• if status = retired, reject for new manifest generation
• if status = deprecated, allow only under review
• if status = draft, allow only under draft/review policy depending on artifact and environment

---

Stage 3 — Resolve artifact type compatibility

Once the opcode row is found, ZAMG must validate whether the resolved artifact type may expose or execute that opcode.

Preferred query

s3-preferred-query.sqlGitHub ↗

SELECT
    b.opcode_artifact_type_binding_id,
    b.opcode,
    b.artifact_type,
    b.binding_status,
    b.exposure_mode,
    b.review_required,
    b.notes
FROM zar.opcode_artifact_type_binding b
WHERE b.opcode = $1
  AND b.artifact_type = $2;

Expected result

Exactly one compatible binding row.

Interpretation

• if row exists and binding_status = active, compatibility is valid
• if row exists and binding_status = draft, allow only with review depending on approval policy
• if no row exists, opcode is not compatible with artifact type

Failure action

If no binding exists:

• mark manifest invalid for approval
• set review class high or reject depending on severity
• do not silently fall back to JSON arrays if strict normalization has been adopted

---

Stage 4 — Resolve ruleset profile guidance

Once opcode and artifact-type compatibility are valid, ZAMG should resolve recommended or required ruleset family/profile bindings.

Preferred query

s4-preferred-query.sqlGitHub ↗

SELECT
    r.opcode_ruleset_profile_binding_id,
    r.opcode,
    r.ruleset_family,
    r.ruleset_profile_code,
    r.binding_strength,          -- required | recommended | optional
    r.environment_scope,
    r.artifact_type,
    r.status,
    r.notes
FROM zar.opcode_ruleset_profile_binding r
WHERE r.opcode = $1
  AND (r.artifact_type = $2 OR r.artifact_type IS NULL)
  AND (r.environment_scope = $3 OR r.environment_scope = 'all')
  AND r.status IN ('active', 'draft')
ORDER BY
    CASE r.binding_strength
        WHEN 'required' THEN 1
        WHEN 'recommended' THEN 2
        WHEN 'optional' THEN 3
        ELSE 4
    END,
    CASE
        WHEN r.artifact_type = $2 THEN 1
        ELSE 2
    END;

Purpose

This does not replace ruleset resolution entirely. It narrows and guides it.

Output use

ZAMG may use this to populate:

• operations[*].routing.ruleset_cmi
• or internal ruleset-family candidate fields
• or review hints if no acceptable binding exists

Rules

• if one required profile exists, use it unless overridden by stricter policy
• if multiple required profiles conflict, trigger review
• if only recommended profiles exist, prefer best fit by artifact type and environment
• if no profile exists, do not fail automatically; treat as warning unless the opcode class demands it

---

Stage 5 — Compute effective defaults

Once the opcode row is valid, ZAMG should compute effective operation defaults.

Fields inherited from opcode registry

• public_api_allowed
• internal_zcp_required
• requires_zssr
• replay_supported
• idempotency_default
• default_execution_mode
• input_contract_type
• output_contract_type
• default_audit_required
• default_human_review_required
• default_retention_class
• default_trust_threshold
• default_geo_scope
• security_class
• compliance_impact
• ai_usage_allowed
• override_requires_approval

Manifest projection mapping

Suggested mapping:

Opcode registry field	Manifest target
public_api_allowed	validate operations[\*].exposure.public_api
internal_zcp_required	operations[\*].exposure.internal_zcp
requires_zssr	operations[\*].routing.via_zssr
default_execution_mode	operations[\*].routing.execution_mode
idempotency_default	operations[\*].http.idempotency_supported or policy equivalent
default_audit_required	operations[\*].policy.audit_required
default_human_review_required	operations[\*].policy.human_review_required
default_retention_class	operations[\*].policy.retention_class
default_trust_threshold	operations[\*].policy.min_trust_score
default_geo_scope	operations[\*].policy.geo_scope

Override rule

Artifact-specific overrides may apply, but:

• if override contradicts opcode governance class
• or if override weakens policy materially
• review must be triggered

---

Stage 6 — Compute review triggers from opcode metadata

ZAMG should compute review sensitivity from opcode governance metadata.

Trigger conditions

Always review if:

• opcode status = deprecated
• opcode status = draft and environment is production
• intent_class in ('disclosure_sensitive', 'governance_sensitive')
• security_class in ('high', 'critical')
• compliance_impact in ('high', 'critical')
• override_requires_approval = true
• requested public API exposure conflicts with public_api_allowed = false

Often review if:

• ai_usage_allowed = false but AI-assisted action is implied in source
• ruleset profile binding is missing for high-impact opcode
• artifact-type binding is draft, not active

---

Stage 7 — Record resolution provenance

Every opcode resolution should be recorded in resolution_meta.

Example

opcode-resolution-example.yamlGitHub ↗

resolution_meta:
  field_resolution:
    operations[0].opcode:
      resolution_mode: "registry_lookup"
      source_ref: "zar.opcode_registry:operation_key=export_xbrl"
      confidence: 1.0
      review_status: "not_required"

    operations[0].routing.ruleset_profile:
      resolution_mode: "registry_lookup"
      source_ref: "zar.opcode_ruleset_profile_binding:opcode=OP_0910"
      confidence: 0.96
      review_status: "not_required"

If compatibility required draft binding:

opcode-compatibility-required-example.yamlGitHub ↗

resolution_meta:
  field_resolution:
    operations[0].artifact_type_opcode_binding:
      resolution_mode: "registry_lookup"
      source_ref: "zar.opcode_artifact_type_binding:opcode=OP_1310,artifact_type=agent_executor"
      confidence: 0.92
      review_status: "review_required"

---

6. Recommended SQL designs additional tables

Table 1 — zar.opcode_registry_change_log

Purpose

Tracks lifecycle, governance, and semantic changes to opcode definitions.

zar-opcode-registry-change-log.sqlGitHub ↗

CREATE TABLE zar.opcode_registry_change_log (
    opcode_registry_change_log_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,

    opcode TEXT NOT NULL,
    operation_key TEXT NOT NULL,

    change_type TEXT NOT NULL,          -- create | update | deprecate | retire | reactivate | policy_change | compatibility_change
    changed_field TEXT,
    old_value JSONB,
    new_value JSONB,

    change_reason TEXT,
    changed_by TEXT NOT NULL,
    approved_by TEXT,

    effective_from TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    CONSTRAINT fk_opcode_registry_change_log_opcode
        FOREIGN KEY (opcode)
        REFERENCES zar.opcode_registry (opcode),

    CONSTRAINT opcode_registry_change_log_change_type_chk
        CHECK (
            change_type = ANY (
                ARRAY[
                    'create',
                    'update',
                    'deprecate',
                    'retire',
                    'reactivate',
                    'policy_change',
                    'compatibility_change'
                ]::TEXT[]
            )
        )
);

CREATE INDEX idx_opcode_registry_change_log_opcode
    ON zar.opcode_registry_change_log (opcode);

CREATE INDEX idx_opcode_registry_change_log_created_at
    ON zar.opcode_registry_change_log (created_at DESC);

Recommended comments

zar-opcode-registry-change-log-comments.sqlGitHub ↗

COMMENT ON TABLE zar.opcode_registry_change_log IS
'Stores lifecycle, compatibility, policy, and semantic change history for opcode definitions in zar.opcode_registry. Used for governance traceability and compatibility review.';

---

Table 2 — zar.opcode_artifact_type_binding

Purpose

Provides strict normalization for opcode ↔ artifact type compatibility.

zar-opcode-artifact-type-binding.sqlGitHub ↗

CREATE TABLE zar.opcode_artifact_type_binding (
    opcode_artifact_type_binding_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,

    opcode TEXT NOT NULL,
    artifact_type TEXT NOT NULL,

    binding_status TEXT NOT NULL DEFAULT 'active',    -- draft | active | deprecated | retired
    exposure_mode TEXT NOT NULL DEFAULT 'internal_only',  -- internal_only | public_optional | public_expected
    review_required BOOLEAN NOT NULL DEFAULT FALSE,
    sort_order INTEGER NOT NULL DEFAULT 100,
    notes TEXT,

    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    CONSTRAINT uq_opcode_artifact_type_binding
        UNIQUE (opcode, artifact_type),

    CONSTRAINT fk_opcode_artifact_type_binding_opcode
        FOREIGN KEY (opcode)
        REFERENCES zar.opcode_registry (opcode),

    CONSTRAINT opcode_artifact_type_binding_status_chk
        CHECK (
            binding_status = ANY (
                ARRAY['draft', 'active', 'deprecated', 'retired']::TEXT[]
            )
        ),

    CONSTRAINT opcode_artifact_type_binding_exposure_mode_chk
        CHECK (
            exposure_mode = ANY (
                ARRAY['internal_only', 'public_optional', 'public_expected']::TEXT[]
            )
        ),

    CONSTRAINT opcode_artifact_type_binding_artifact_type_chk
        CHECK (
            artifact_type IN (
                'engine',
                'micro_engine',
                'validator',
                'router',
                'exporter',
                'ruleset',
                'parser',
                'transformer',
                'workflow_dispatcher',
                'connector',
                'agent_executor',
                'registry_adapter',
                'governance_adapter'
            )
        ),

    CONSTRAINT opcode_artifact_type_binding_sort_order_chk
        CHECK (sort_order >= 0)
);

CREATE INDEX idx_opcode_artifact_type_binding_opcode
    ON zar.opcode_artifact_type_binding (opcode);

CREATE INDEX idx_opcode_artifact_type_binding_artifact_type
    ON zar.opcode_artifact_type_binding (artifact_type);

CREATE INDEX idx_opcode_artifact_type_binding_status
    ON zar.opcode_artifact_type_binding (binding_status);

CREATE OR REPLACE FUNCTION zar.set_updated_at_opcode_artifact_type_binding()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at := NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_set_updated_at_opcode_artifact_type_binding
BEFORE UPDATE ON zar.opcode_artifact_type_binding
FOR EACH ROW
EXECUTE FUNCTION zar.set_updated_at_opcode_artifact_type_binding();

Recommended comments

zar-opcode-artifact-type-binding-comments.sqlGitHub ↗

COMMENT ON TABLE zar.opcode_artifact_type_binding IS
'Strict compatibility bindings between opcodes and artifact types. Used by ZAMG to validate whether an artifact type may expose or execute a given opcode.';

---

Table 3 — zar.opcode_ruleset_profile_binding

Purpose

Defines recommended or required ruleset families/profiles by opcode, optionally scoped by artifact type and environment.

zar-opcode-ruleset-profile-binding.sqlGitHub ↗

CREATE TABLE zar.opcode_ruleset_profile_binding (
    opcode_ruleset_profile_binding_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,

    opcode TEXT NOT NULL,
    artifact_type TEXT,
    environment_scope TEXT NOT NULL DEFAULT 'all',     -- all | internal | preview | staging | production
    ruleset_family TEXT NOT NULL,
    ruleset_profile_code TEXT NOT NULL,

    binding_strength TEXT NOT NULL DEFAULT 'recommended',   -- required | recommended | optional
    status TEXT NOT NULL DEFAULT 'active',                  -- draft | active | deprecated | retired
    sort_order INTEGER NOT NULL DEFAULT 100,
    notes TEXT,

    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    CONSTRAINT uq_opcode_ruleset_profile_binding
        UNIQUE (opcode, artifact_type, environment_scope, ruleset_profile_code),

    CONSTRAINT fk_opcode_ruleset_profile_binding_opcode
        FOREIGN KEY (opcode)
        REFERENCES zar.opcode_registry (opcode),

    CONSTRAINT opcode_ruleset_profile_binding_binding_strength_chk
        CHECK (
            binding_strength = ANY (
                ARRAY['required', 'recommended', 'optional']::TEXT[]
            )
        ),

    CONSTRAINT opcode_ruleset_profile_binding_status_chk
        CHECK (
            status = ANY (
                ARRAY['draft', 'active', 'deprecated', 'retired']::TEXT[]
            )
        ),

    CONSTRAINT opcode_ruleset_profile_binding_environment_scope_chk
        CHECK (
            environment_scope = ANY (
                ARRAY['all', 'internal', 'preview', 'staging', 'production']::TEXT[]
            )
        ),

    CONSTRAINT opcode_ruleset_profile_binding_artifact_type_chk
        CHECK (
            artifact_type IS NULL OR artifact_type IN (
                'engine',
                'micro_engine',
                'validator',
                'router',
                'exporter',
                'ruleset',
                'parser',
                'transformer',
                'workflow_dispatcher',
                'connector',
                'agent_executor',
                'registry_adapter',
                'governance_adapter'
            )
        ),

    CONSTRAINT opcode_ruleset_profile_binding_sort_order_chk
        CHECK (sort_order >= 0)
);

CREATE INDEX idx_opcode_ruleset_profile_binding_opcode
    ON zar.opcode_ruleset_profile_binding (opcode);

CREATE INDEX idx_opcode_ruleset_profile_binding_artifact_type
    ON zar.opcode_ruleset_profile_binding (artifact_type);

CREATE INDEX idx_opcode_ruleset_profile_binding_environment_scope
    ON zar.opcode_ruleset_profile_binding (environment_scope);

CREATE INDEX idx_opcode_ruleset_profile_binding_status
    ON zar.opcode_ruleset_profile_binding (status);

CREATE OR REPLACE FUNCTION zar.set_updated_at_opcode_ruleset_profile_binding()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at := NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_set_updated_at_opcode_ruleset_profile_binding
BEFORE UPDATE ON zar.opcode_ruleset_profile_binding
FOR EACH ROW
EXECUTE FUNCTION zar.set_updated_at_opcode_ruleset_profile_binding();

Recommended comments

zar-opcode-ruleset-profile-binding-comments.sqlGitHub ↗

COMMENT ON TABLE zar.opcode_ruleset_profile_binding IS
'Stores required, recommended, or optional ruleset family/profile guidance for each opcode, optionally scoped by artifact type and environment. Used by ZAMG and routing validation to narrow ruleset selection.';

---

7. Recommended resolution query bundle

Here is the practical query sequence ZAMG should use.

Step 1: resolve opcode

s1-resolve-opcode.sqlGitHub ↗

SELECT *
FROM zar.opcode_registry
WHERE operation_key = $1;

Step 2: validate artifact type compatibility

s2-validate-artifact-type-compatibility.sqlGitHub ↗

SELECT *
FROM zar.opcode_artifact_type_binding
WHERE opcode = $1
  AND artifact_type = $2
  AND binding_status IN ('active', 'draft')
ORDER BY
  CASE binding_status WHEN 'active' THEN 1 ELSE 2 END,
  sort_order;

Step 3: fetch ruleset profile guidance

s3-fetch-ruleset-profile-guidance.sqlGitHub ↗

SELECT *
FROM zar.opcode_ruleset_profile_binding
WHERE opcode = $1
  AND (artifact_type = $2 OR artifact_type IS NULL)
  AND environment_scope IN ($3, 'all')
  AND status IN ('active', 'draft')
ORDER BY
  CASE binding_strength
    WHEN 'required' THEN 1
    WHEN 'recommended' THEN 2
    ELSE 3
  END,
  CASE WHEN artifact_type = $2 THEN 1 ELSE 2 END,
  sort_order;

Step 4: check recent change history when needed

s4-check-recent-change-history.sqlGitHub ↗

SELECT *
FROM zar.opcode_registry_change_log
WHERE opcode = $1
ORDER BY created_at DESC
LIMIT 20;

Use this especially when:

• opcode is deprecated
• binding recently changed
• policy-sensitive review is needed

---

8. Recommended seed strategy for the new tables

opcode_artifact_type_binding

Seed one row per allowed combination from the opcode registry draft.

opcode_ruleset_profile_binding

Seed only the high-value opcodes first, for example:

• OP_0420 run_ruleset_validation
• OP_0700 route_next
• OP_0800 dispatch_workflow
• OP_0910 export_xbrl
• OP_0920 export_ixbrl
• OP_0930 publish_disclosure
• OP_0940 sign_output

opcode_registry_change_log

Do not backfill heavily at first unless you want full historical reconstruction. Start using it from now on.

---