Jira progress: loading…

ESGX

Opcode alias for External Stakeholders

The ESG Exchange Code (ESG) is the ZAYAZ external opcode alias layer. An ESGX code is a compact, partner- or client-scoped execution handle that resolves to a pre-governed ZCP execution profile inside the platform.

1. Description

An ESGX code is not a new canonical opcode. Instead, it is a lookup key that maps to:

a canonical core opcode
a semantic operation key
a target resolution strategy or artifact binding
optional default parameters
ruleset profile hints or requirements
authentication and exposure constraints
ZSSR routing requirements
partner/client-specific execution context

This allows ZAYAZ to expose compact external command handles without polluting the canonical core opcode registry.

An ESGX code typically follows the compact + lookup structure:

ESGX_<hash>_<opcode_suffix>

Example:

ESGX_4jbj6c76_0950

In this model:

ESGX identifies the external opcode alias family
<hash> identifies the partner-scoped or binding-specific alias
<opcode_suffix> provides a lightweight semantic anchor to the underlying core opcode family

At runtime, an ESGX code is resolved through a governed alias binding registry into a canonical ZCP command profile. Execution still routes through ZSSR and follows the same policy, routing, trust, and lifecycle controls as any other governed ZCP invocation.

ESGX codes can be used for:

partner-specific command entrypoints
saved or reusable API requests
client-scoped shortcuts
external integration bindings
preconfigured execution profiles

Partners may be allowed to define or save their own ESGX bindings, but these bindings always resolve into approved core ZAYAZ semantics rather than creating a parallel opcode universe.

Summary

ESGX is the external alias layer for ZAYAZ opcodes. An ESGX code is a compact lookup key that resolves to a governed ZCP execution profile, including core opcode mapping, target context, parameter defaults, and ZSSR routing requirements. ESGX aliases are partner- or client-scoped shortcuts, not new canonical opcodes.

2. ESGX Resolution Spec

2.1. Purpose

This specification defines how an ESGX alias is resolved into a governed ZCP execution profile.

It covers:

lookup rules
lifecycle/status checks
partner/client scoping
opcode resolution
target resolution
default parameter injection
API route binding interaction
ZSSR enforcement
output projection

2.2. Core principle

ESGX is a compact external handle that resolves into canonical ZCP semantics.

That means:

ESGX does not define new semantic intent
ESGX resolves to operation_key + opcode
ESGX may add scoped execution context and defaults
ESGX always remains subordinate to core opcode governance

2.3. Resolution inputs

An inbound ESGX resolution request may include:

ESGX_code
caller auth context
partner/client/tenant identity
optional API route context
optional payload
environment scope
optional request override values

2.4. Resolution stages

Stage 1 — Parse and validate ESGX format

Input:

ESGX_4jbj6c76_0950

Validate:

prefix = ESGX
hash segment valid
opcode suffix valid

If invalid:

reject with ESGX_format_invalid

Stage 2 — Lookup binding row

Lookup by:

ESGX_code or
(ESGX_hash, opcode_suffix)

Primary lookup:

primary-lookup.sqlGitHub ↗
SELECT *
FROM zar.external_opcode_binding_registry
WHERE ESGX_code = $1;

If not found:

reject with ESGX_binding_not_found

Stage 3 — Lifecycle and validity checks

Validate:

status = active
lifecycle_status = active
current timestamp within valid_from / valid_to if set
alias not suspended or retired

If failed:

reject with ESGX_binding_inactive

Stage 4 — Caller scope validation

Validate caller against:

partner_id
client_id
tenant_id
owner_org_id
caller_scope_mode
auth_profile_code

Examples:

partner-scoped alias callable only by that partner
client-scoped alias callable only by the bound client
org-scoped alias callable only within matching org

If failed:

reject with ESGX_scope_denied

Stage 5 — Resolve canonical semantic target

Resolve:

operation_key
opcode

Validate:

opcode exists in zar.opcode_registry
opcode status compatible with runtime use
artifact type compatible through zar.opcode_artifact_type_binding

If failed:

reject with ESGX_opcode_resolution_failed

Stage 6 — Resolve route binding if applicable

If api_binding_id is present:

fetch zar.api_route_binding_registry
validate route binding status/lifecycle
merge compatible request/response mapping information

If route_binding_required = true and no valid route binding exists:

reject with ESGX_route_binding_required

Stage 7 — Resolve runtime target

Use target_resolution_mode:

explicit_cmi

Use fixed target CMI.

artifact_type

Resolve through artifact type + opcode compatibility.

manifest_capability

Resolve through approved manifests and capability tables.

api_binding

Use the associated API binding as the main resolution profile.

workflow_template

Resolve to pre-approved workflow dispatch target.

If target cannot be resolved:

reject with ESGX_target_resolution_failed

Stage 8 — Build effective input payload

Merge in this order:

binding default_input_payload
caller-provided payload
allowed override policy from request_constraints

Then inject:

fixed_context
caller scope metadata
auth context metadata
route binding metadata if present

This creates the effective ZCP input payload.

Stage 9 — Build effective ZCP command

Resulting command should include:

operation_key
opcode
target info
input/output contract types
execution mode
ruleset profile
auth profile
partner/client scope metadata
ZSSR requirement
trust/security/compliance metadata
trace metadata indicating ESGX source

Example:

zcp-command.yamlGitHub ↗
zcp_version: "0.1"
command_id: "cmd_01J..."
operation_key: "pull_from_external_system"
opcode: "OP_1410"

source:
  invoked_via: "ESGX"
  ESGX_code: "ESGX_4jbj6c76_0950"
  external_binding_id: 42

target:
  artifact_type: "connector"
  cmi: "...."

routing:
  via_zssr: true
  ruleset_profile_code: "BIGCORP_QREPORT_PULL_V1"

context:
  partner_id: "partner_bigcorp"
  client_id: "client_bigcorp"
  caller_scope_mode: "partner_scoped"

input:
  contract_type: "external_pull_request"
  payload:
    report_type: "quarterly"
    latest: true
    client_code: "bigcorp"

Stage 10 — Execute through ZSSR

Even when direct ESGX invocation is allowed:

runtime execution still goes through ZSSR
policy/ruleset enforcement still applies
trust/governance checks still apply

This is mandatory.

Stage 11 — Project result back to caller

Use:

output_contract_type
response_projection
optional api_binding_id response mapping
caller visibility rules

The caller receives:

result payload
async job tracking if relevant
warnings/errors
possibly reduced trace metadata depending on exposure policy

2.5. Resolution precedence rules

Rule 1

ESGX_code is the primary lookup key.

Rule 2

Core opcode remains the canonical semantic execution anchor.

Rule 3

Binding defaults may constrain or enrich input, but may not override core opcode meaning.

Rule 4

Route binding metadata may refine translation, but may not contradict core opcode governance.

Rule 5

Ruleset-specific behavior should be carried in ruleset_profile_code, not in new core opcodes.

Rule 6

ESGX may shortcut generic API translation, but may not bypass ZSSR.

2.6. Recommended ESGX use cases

Use ESGX for:

partner-specific command entrypoints
saved API requests
preconfigured client pulls or exports
compact external integration handles
reusable direct execution profiles

Do not use ESGX for:

arbitrary hidden workflows without governance
bypassing policy or review
inventing new semantic operations
encoding large logic directly in the alias string

2.7. Failure classes

Recommended failure classes:

ESGX_format_invalid
ESGX_binding_not_found
ESGX_binding_inactive
ESGX_scope_denied
ESGX_opcode_resolution_failed
ESGX_route_binding_required
ESGX_target_resolution_failed
ESGX_request_constraints_failed
ESGX_execution_denied_by_zssr

2.8. Partner-defined or saved ESGX bindings

Yes — the architecture supports this.

Partners may:

define their own ESGX bindings
save approved API requests as ESGX bindings
create reusable scoped aliases

But only if:

binding creation is governed
target opcode is canonical and approved
execution still routes through ZSSR
scope/auth rules are enforced
lifecycle state is managed

That gives you both flexibility and control.

2.9. Recommendation on alias format

Yes — your preferred format works very well:

ESGX_<hash>_<opcode_suffix>

Example:

ESGX_4jbj6c76_0950

This gives:

compactness
scale
security through indirection
debugging value via opcode-family anchor
clean partner-facing identifiers

Keep the canonical opcode itself in the registry row, while exposing only the suffix in the alias.

Final summary

This design gives ZAYAZ:

a canonical core opcode layer
an API route binding layer
an external alias layer
one governed execution path through ZCP + ZSSR

3. zar.external_opcode_binding_registry

This table stores compact external opcode aliases (ESGX) that resolve into governed ZCP execution profiles.

Seed examples for zar.external_opcode_binding_registry

seed-example-external-opcode-binding-registry.sqlGitHub ↗
INSERT INTO zar.external_opcode_binding_registry (
    ESGX_code,
    ESGX_hash,
    opcode_suffix,
    binding_name,
    description,
    partner_id,
    client_id,
    tenant_id,
    owner_org_id,
    operation_key,
    opcode,
    api_binding_id,
    artifact_type,
    target_resolution_mode,
    target_cmi,
    target_cmi_version,
    ruleset_profile_code,
    auth_profile_code,
    execution_mode,
    requires_zssr,
    idempotency_supported,
    partner_api_allowed,
    direct_ESGX_allowed,
    internal_api_allowed,
    tenant_scope_mode,
    caller_scope_mode,
    input_contract_type,
    output_contract_type,
    default_input_payload,
    fixed_context,
    request_constraints,
    response_projection,
    route_binding_required,
    route_binding_override_allowed,
    usage_limit_profile,
    security_class,
    compliance_impact,
    trust_threshold,
    status,
    lifecycle_status,
    version,
    sort_order,
    valid_from,
    valid_to,
    source_notes
) VALUES

(
    'ESGX_4jbj6c76_1410',
    '4jbj6c76',
    '1410',
    'BigCorp Latest Quarterly Report Pull',
    'Partner-scoped ESGX alias for pulling the latest quarterly report for BigCorp.',
    'partner_bigcorp',
    'client_bigcorp',
    NULL,
    'org_bigcorp',
    'pull_from_external_system',
    'OP_1410',
    'api.reports.quarterly.pull.post.v1',
    'connector',
    'manifest_capability',
    NULL,
    NULL,
    'BIGCORP_QREPORT_PULL_V1',
    'partner_bearer_v1',
    'async',
    TRUE,
    TRUE,
    TRUE,
    TRUE,
    FALSE,
    'caller_scoped',
    'partner_scoped',
    'external_pull_request',
    'external_pull_result',
    '{"report_type":"quarterly","latest":true,"client_code":"bigcorp"}'::jsonb,
    '{"invoked_via":"ESGX","partner_context":"bigcorp"}'::jsonb,
    '{"allow_period_override":false,"allow_client_override":false}'::jsonb,
    '{"profile":"bigcorp_qreport_response_v1"}'::jsonb,
    FALSE,
    FALSE,
    'partner_standard',
    'high',
    'medium',
    0.8800,
    'active',
    'active',
    '1_0_0',
    100,
    NULL,
    NULL,
    NULL
),

(
    'ESGX_7md8ka21_0910',
    '7md8ka21',
    '0910',
    'Partner XBRL Export Shortcut',
    'Partner-scoped ESGX alias for exporting an approved disclosure package as XBRL.',
    'partner_reportinghub',
    NULL,
    NULL,
    'org_reportinghub',
    'export_xbrl',
    'OP_0910',
    'api.exports.xbrl.post.v1',
    'exporter',
    'api_binding',
    NULL,
    NULL,
    'XBRL_EXPORT_DEFAULT',
    'partner_bearer_v1',
    'hybrid',
    TRUE,
    TRUE,
    TRUE,
    TRUE,
    FALSE,
    'caller_scoped',
    'partner_scoped',
    'report_package',
    'disclosure_artifact',
    '{"taxonomy":"ESRS"}'::jsonb,
    '{"invoked_via":"ESGX"}'::jsonb,
    '{"allow_taxonomy_override":true}'::jsonb,
    '{"profile":"xbrl_export_response_v1"}'::jsonb,
    FALSE,
    TRUE,
    'partner_standard',
    'high',
    'critical',
    0.9200,
    'active',
    'active',
    '1_0_0',
    110,
    NULL,
    NULL,
    NULL
),

(
    'ESGX_2kr91pz4_0600',
    '2kr91pz4',
    '0600',
    'Client Scope 2 Metric Compute',
    'Client-scoped ESGX alias for computing a preconfigured Scope 2 market-based metric.',
    NULL,
    'client_nordicsteel',
    NULL,
    'org_nordicsteel',
    'compute_metric',
    'OP_0600',
    'api.metrics.compute.post.v1',
    'micro_engine',
    'manifest_capability',
    NULL,
    NULL,
    'SCOPE2_MB_DEFAULT',
    'client_bearer_v1',
    'sync',
    TRUE,
    TRUE,
    TRUE,
    TRUE,
    FALSE,
    'caller_scoped',
    'client_scoped',
    'signal_set',
    'signal_set',
    '{"metric_key":"scope_2_market_based"}'::jsonb,
    '{"invoked_via":"ESGX","client_context":"nordicsteel"}'::jsonb,
    '{"allow_metric_override":false}'::jsonb,
    '{"profile":"metric_compute_response_v1"}'::jsonb,
    FALSE,
    FALSE,
    'client_standard',
    'medium',
    'medium',
    0.8500,
    'active',
    'active',
    '1_0_0',
    120,
    NULL,
    NULL,
    NULL
),

(
    'ESGX_q8ls5v2n_0810',
    'q8ls5v2n',
    '0810',
    'Compliance Review Escalation Alias',
    'Internal partner-scoped ESGX alias for creating a governed human review request.',
    'partner_assuranceco',
    NULL,
    NULL,
    'org_assuranceco',
    'request_human_review',
    'OP_0810',
    'api.reviews.request.post.v1',
    'workflow_dispatcher',
    'workflow_template',
    NULL,
    NULL,
    'HUMAN_REVIEW_DEFAULT',
    'partner_bearer_v1',
    'async',
    TRUE,
    FALSE,
    TRUE,
    TRUE,
    FALSE,
    'caller_scoped',
    'partner_scoped',
    'review_request',
    'review_request_result',
    '{}'::jsonb,
    '{"invoked_via":"ESGX","review_origin":"assurance_partner"}'::jsonb,
    '{"allow_reason_override":true}'::jsonb,
    '{"profile":"review_request_response_v1"}'::jsonb,
    FALSE,
    FALSE,
    'partner_restricted',
    'high',
    'critical',
    0.9500,
    'active',
    'active',
    '1_0_0',
    130,
    NULL,
    NULL,
    NULL
),

(
    'ESGX_m3cv9t7x_0800',
    'm3cv9t7x',
    '0800',
    'Workflow Dispatch Preset',
    'Partner-scoped ESGX alias for dispatching a pre-approved workflow template.',
    'partner_ecoadvisory',
    NULL,
    NULL,
    'org_ecoadvisory',
    'dispatch_workflow',
    'OP_0800',
    'api.workflows.dispatch.post.v1',
    'workflow_dispatcher',
    'workflow_template',
    NULL,
    NULL,
    'WORKFLOW_DISPATCH_DEFAULT',
    'partner_bearer_v1',
    'async',
    TRUE,
    TRUE,
    TRUE,
    TRUE,
    FALSE,
    'caller_scoped',
    'partner_scoped',
    'workflow_request',
    'workflow_result',
    '{"workflow_key":"quarterly_disclosure_refresh"}'::jsonb,
    '{"invoked_via":"ESGX"}'::jsonb,
    '{"allow_workflow_override":false}'::jsonb,
    '{"profile":"workflow_dispatch_response_v1"}'::jsonb,
    FALSE,
    FALSE,
    'partner_standard',
    'high',
    'high',
    0.9000,
    'active',
    'active',
    '1_0_0',
    140,
    NULL,
    NULL,
    NULL
);

Example bindings

Route bindings

esgx_code	partner_id	client_id	operation_key	opcode	api_binding_id	artifact_type	execution_mode
ESGX_4jbj6c76_1410	partner_bigcorp	client_bigcorp	pull_from_external_system	OP_1410	api.reports.quarterly.pull.post.v1	connector	async
ESGX_7md8ka21_0910	partner_reportinghub		export_xbrl	OP_0910	api.exports.xbrl.post.v1	exporter	hybrid
ESGX_2kr91pz4_0600		client_nordicsteel	compute_metric	OP_0600	api.metrics.compute.post.v1	micro_engine	sync
ESGX_q8ls5v2n_0810	partner_assuranceco		request_human_review	OP_0810	api.reviews.request.post.v1	workflow_dispatcher	async

4. ESGX hash generation model

Alias format

ESGX_<hash>_<opcode_suffix>

Where:

ESGX = external alias family
<hash> = deterministic compact binding fingerprint
<opcode_suffix> = last 4 digits of canonical opcode

4.1. The hash is based on a specific fingerprint

scope discriminator
- partner_id
- or client_id
- or tenant_id
- or owner_org_id
operation_key
opcode
api_binding_id if present
artifact_type
ruleset_profile_code if present
target_resolution_mode
a normalized default-input signature

The hash identifies the resolved execution binding

4.2.

Example canonical fingerprint string

For example: partner_bigcorp|client_bigcorp||org_bigcorp|pull_from_external_system|OP_1410|api.reports.quarterly.pull.post.v1|connector|manifest_capability|BIGCORP_QREPORT_PULL_V1|{"client_code":"bigcorp","latest":true,"report_type":"quarterly"}

Then:

normalize
hash
take a short prefix

Algorithm

We use:

SHA-256
lowercase hex output
take first 8 chars

Example result:

4jbj6c76

4.3. Collision handling

Eight chars is usually enough for this use case, but collisions are still theoretically possible.

Collision rule

If generated hash already exists for a different fingerprint:

try first 10 chars
then 12 chars
or append a deterministic sequence suffix

Recommended:

default = 8 chars
extend to 10 if collision
extend to 12 if needed

That keeps aliases short while staying safe.

4.4. Important design rule

The hash should be generated from the binding payload, but the stored row should also keep the full canonical fingerprint or fingerprint hash for traceability.

So in the registry, we're adding:

binding_fingerprint text
binding_fingerprint_sha256 text

Even if esgx_hash is only 8 chars.

That gives us:

auditability
rebuildability
collision diagnosis

4.5. Recommended generation steps

Step 1 — Build canonical normalized fingerprint object

Example logical object:

narmalized-fingerprint-object.jsonGitHub ↗
{
  "partner_id": "partner_bigcorp",
  "client_id": "client_bigcorp",
  "tenant_id": null,
  "owner_org_id": "org_bigcorp",
  "operation_key": "pull_from_external_system",
  "opcode": "OP_1410",
  "api_binding_id": "api.reports.quarterly.pull.post.v1",
  "artifact_type": "connector",
  "target_resolution_mode": "manifest_capability",
  "ruleset_profile_code": "BIGCORP_QREPORT_PULL_V1",
  "default_input_payload": {
    "client_code": "bigcorp",
    "latest": true,
    "report_type": "quarterly"
  }
}

Step 2 — Serialize canonically

Keys sorted, stable JSON, no formatting drift.

Step 3 — SHA-256 hash it

Step 4 — Take first 8 chars

Example:

4jbj6c76

Step 5 — Build alias

Take opcode suffix from OP_1410 → 1410

Final:

ESGX_4jbj6c76_1410

4.6. What should NOT be included in the hash

Do not include fields that change frequently but do not change semantic identity:

binding_name
description
sort_order
status
approved_by
timestamps
notes

Those would make hashes unstable for no good reason.

4.7. Partner defined ESGX bindings

Partners can define their own ESGX bindings, but the platform still generate the hash

The partner may define:

target
defaults
route binding
scope
ruleset profile

But ZAYAZ generates:

canonical fingerprint
deterministic hash
final ESGX code

That avoids chaos 😉

4.8. Suggested pseudo-code

pseudo-code-1.tsGitHub ↗
function buildESGXFingerprint(input: {
  partner_id?: string | null;
  client_id?: string | null;
  tenant_id?: string | null;
  owner_org_id?: string | null;
  operation_key: string;
  opcode: string;
  api_binding_id?: string | null;
  artifact_type: string;
  target_resolution_mode: string;
  ruleset_profile_code?: string | null;
  default_input_payload?: Record<string, unknown> | null;
}): string {
  return stableStringify({
    partner_id: input.partner_id ?? null,
    client_id: input.client_id ?? null,
    tenant_id: input.tenant_id ?? null,
    owner_org_id: input.owner_org_id ?? null,
    operation_key: input.operation_key,
    opcode: input.opcode,
    api_binding_id: input.api_binding_id ?? null,
    artifact_type: input.artifact_type,
    target_resolution_mode: input.target_resolution_mode,
    ruleset_profile_code: input.ruleset_profile_code ?? null,
    default_input_payload: input.default_input_payload ?? {},
  });
}

pseudo-code-2.tsGitHub ↗
import { createHash } from "crypto";

export function generateESGXCode(fingerprint: string, opcode: string): string {
  const fullHash = createHash("sha256")
    .update(fingerprint)
    .digest("hex")
    .toLowerCase();

  const shortHash = fullHash.slice(0, 8);
  const opcodeSuffix = opcode.replace(/^OP_/, "");

  return `ESGX_${shortHash}_${opcodeSuffix}`;
}

GitHub Repo Request for Change (RFC)

1. Description​

Summary​

2. ESGX Resolution Spec​

2.1. Purpose​

2.2. Core principle​

2.3. Resolution inputs​

2.4. Resolution stages​

2.5. Resolution precedence rules​

2.6. Recommended ESGX use cases​

2.7. Failure classes​

2.8. Partner-defined or saved ESGX bindings​

2.9. Recommendation on alias format​

Final summary​

3. zar.external_opcode_binding_registry​

Seed examples for zar.external_opcode_binding_registry​

Example bindings​

4. ESGX hash generation model​

4.1. The hash is based on a specific fingerprint​

4.2.​

4.3. Collision handling​

4.4. Important design rule​

4.5. Recommended generation steps​

4.6. What should NOT be included in the hash​

4.7. Partner defined ESGX bindings​

4.8. Suggested pseudo-code​

1. Description

Summary

2. ESGX Resolution Spec

2.1. Purpose

2.2. Core principle

2.3. Resolution inputs

2.4. Resolution stages

2.5. Resolution precedence rules

2.6. Recommended ESGX use cases

2.7. Failure classes

2.8. Partner-defined or saved ESGX bindings

2.9. Recommendation on alias format

Final summary

3. zar.external_opcode_binding_registry

Seed examples for zar.external_opcode_binding_registry

Example bindings

4. ESGX hash generation model

4.1. The hash is based on a specific fingerprint

4.2.

4.3. Collision handling

4.4. Important design rule

4.5. Recommended generation steps

4.6. What should NOT be included in the hash

4.7. Partner defined ESGX bindings

4.8. Suggested pseudo-code