@passioncode-ai/fabric-agent-adapter 0.35.3 → 0.36.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-interop.mjs

@@ -9,6 +9,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { ServiceError, atomicWrite, ensurePrivateDir, nowIso } from './fabric-service.mjs';
+import { jcs } from './fabric-delegation.mjs';
 
 export const PROTOCOL = 'fabric-interop/0.1';
 export const EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1';
@@ -94,19 +95,25 @@ export const unknownJobResult = (jobId, traceparent) =>
   toolResult({ error: { code: 'unknown-job', message: `No job ${jobId} here.` } }, { isError: true, traceparent });
 
 // --- C3.2 the result envelope --------------------------------------------------------------
-function checkUsage(usage) {
+function checkUsage(usage, nulls = false) {
   if (!usage || typeof usage !== 'object') throw new InteropError('usage must be an object.');
   for (const key of ['inputTokens', 'outputTokens', 'wallMs']) if (!(key in usage)) throw new InteropError(`usage.${key} is required.`);
   for (const [key, value] of Object.entries(usage)) {
+    if (nulls && key === 'partial') {
+      if (typeof value !== 'boolean') throw new InteropError('usage.partial must be a boolean.');
+      continue;
+    }
     if (!USAGE_KEYS.includes(key)) throw new InteropError(`usage.${key} is not a usage field.`);
+    if (nulls && value === null) continue;
     const ok = typeof value === 'number' && value >= 0 && (key === 'costUsd' || Number.isInteger(value));
     if (!ok) throw new InteropError(`usage.${key} must be a non-negative ${key === 'costUsd' ? 'number' : 'integer'}.`);
   }
+  if (nulls && usageFindings(usage, '').length) throw new InteropError('usage.partial is false while a number is null: an unknown number makes the usage partial (FAC-SEM-119).');
   return { ...usage };
 }
 
 // The full result envelope (contract result.schema.json, DEC-0017): the shape a synchronous call returns.
-export function resultEnvelope({ outcome, done, proof, scope, notVerified, output, usage, producer, artifacts = [], traceparent, id, createdAt }) {
+export function resultEnvelope({ outcome, done, proof, scope, notVerified, output, usage, producer, artifacts = [], traceparent, id, createdAt, requestMeta }) {
   if (!OUTCOMES.includes(outcome)) throw new InteropError(`outcome must be one of ${OUTCOMES.join(', ')}.`);
   for (const [label, value] of [['done', done], ['proof', proof], ['notVerified', notVerified], ['artifacts', artifacts]]) {
     if (!Array.isArray(value)) throw new InteropError(`${label} must be a list, even when empty.`);
@@ -116,12 +123,206 @@ export function resultEnvelope({ outcome, done, proof, scope, notVerified, outpu
   const envelope = {
     id: id ?? `urn:fabric:result:${crypto.randomBytes(12).toString('hex')}`, contractVersion: CONTRACT_VERSION, outcome,
     done: [...done], proof: [...proof], scope: { ...scope }, notVerified: [...notVerified], artifacts: [...artifacts],
-    createdAt: createdAt ?? nowIso(), producer: { ...producer }, output, usage: checkUsage(usage),
+    createdAt: createdAt ?? nowIso(), producer: { ...producer }, output, usage: usageToward(usage, requestMeta),
   };
   if (parseTraceparent(traceparent)) envelope.trace = { traceparent };
   return envelope;
 }
 
+// --- C3.2 limits and uncertain effects (DEC-0087) ------------------------------------------
+// #region job-limits-kit-node, docs: plugins/fabric-agent-adapter/skills/building-fabric-services/references/interop.md#limits-and-uncertain-effects
+// The contract's src/job-limits.ts, answer for answer (test/fixtures/contract/job-limit-vectors.json), the twin of
+// fabric_interop.py. Every function here answers and never throws on malformed input.
+
+export const QUOTA_EXHAUSTED = 'quota-exhausted';
+export const OUTCOME_UNKNOWN = 'outcome-unknown';
+export const LIMIT_REACHED = 'limit-reached';
+export const INTEROP_NULL_USAGE = 'fabric-interop/0.2';
+/** The revisions this kit reads, named in a request's `_meta.protocols` (DEC-0067, DEC-0087). */
+export const PROTOCOLS_READ = Object.freeze(['fabric-interop/0.1', INTEROP_NULL_USAGE]);
+const JOB_STATUSES = ['working', 'input_required', 'completed', 'failed', 'cancelled'];
+const UTC_INSTANT = /^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-5][0-9])(?:\.([0-9]{1,3}))?Z$/;
+const PAUSE = /^quota-exhausted(?: until ([^ \t\n\r]+?))?(?:: ([ \t\n\r]*[^ \t\n\r][\s\S]*))?$/;
+const ERROR_CODE = /^[a-z][a-z0-9-]{1,63}$/;
+const MAX_STATUS_MESSAGE = 500;
+const MAX_ERROR_MESSAGE = 2000;
+const codePoints = (value) => [...value].length;
+const isString = (value) => typeof value === 'string';
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const own = (value, key) => (isObject(value) && Object.hasOwn(value, key) ? value[key] : undefined);
+
+/** A UTC instant as milliseconds, or NaN: the pattern and a day that exists, as the contract's strictTime reads it. */
+export function utcTime(value) {
+  const m = isString(value) ? UTC_INSTANT.exec(value) : null;
+  if (!m) return Number.NaN;
+  const [year, month, day, hour, minute, second] = m.slice(1, 7).map(Number);
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day || hour > 23 || minute > 59) return Number.NaN;
+  date.setUTCHours(hour, minute, second, Number((m[7] ?? '').padEnd(3, '0')));
+  return date.getTime();
+}
+
+export function quotaDataOk(data) {
+  const retryable = own(data, 'retryable');
+  if (!isObject(data) || typeof retryable !== 'boolean') return false;
+  if (Object.keys(data).some((name) => name !== 'retryable' && name !== 'resetsAt')) return false;
+  if (!Object.hasOwn(data, 'resetsAt')) return true;
+  return retryable && Number.isFinite(utcTime(own(data, 'resetsAt')));
+}
+
+function jobOf(answer) {
+  const job = own(answer, 'job');
+  const id = own(job, 'id');
+  if (!isObject(job) || !isString(id) || id.length === 0 || !JOB_STATUSES.includes(own(job, 'status'))) return undefined;
+  return job;
+}
+
+export function readJobPause(answer) {
+  const job = jobOf(answer);
+  const message = own(job, 'statusMessage');
+  if (!job || own(job, 'status') !== 'working' || !isString(message) || !message.startsWith(QUOTA_EXHAUSTED)) return { paused: false };
+  const match = PAUSE.exec(message);
+  if (!match || codePoints(message) > MAX_STATUS_MESSAGE) return { paused: false, malformed: true };
+  const until = match[1];
+  if (until === undefined) return { paused: true };
+  return Number.isFinite(utcTime(until)) ? { paused: true, resetsAt: until } : { paused: false, malformed: true };
+}
+
+/** What a caller does with one fabric.job.get or fabric.job.cancel answer at `now`; never "submit anew". */
+export function jobCallerAction(answer, now) {
+  const at = utcTime(now);
+  const job = jobOf(answer);
+  if (!Number.isFinite(at) || !job) return { action: 'invalid' };
+  const status = own(job, 'status');
+  if (status === 'working') {
+    const pause = readJobPause(answer);
+    if ('malformed' in pause) return { action: 'invalid' };
+    if (!pause.paused) return { action: 'poll' };
+    if (pause.resetsAt === undefined) return { action: 'wait' };
+    return utcTime(pause.resetsAt) > at ? { action: 'wait', notBefore: pause.resetsAt } : { action: 'poll' };
+  }
+  if (status === 'input_required') return { action: 'answer' };
+  if (status === 'completed') return { action: 'done' };
+  if (status === 'cancelled') return { action: 'cancelled' };
+  const error = own(job, 'error');
+  const code = own(error, 'code');
+  const message = own(error, 'message');
+  const codeOk = (isString(code) && ERROR_CODE.test(code)) || Number.isInteger(code);
+  const shapeOk = isObject(error) && Object.keys(error).every((name) => name === 'code' || name === 'message' || name === 'data');
+  if (!shapeOk || !codeOk || !isString(message) || message.length === 0 || codePoints(message) > MAX_ERROR_MESSAGE) return { action: 'invalid' };
+  if (code === OUTCOME_UNKNOWN) return { action: 'reconcile' };
+  if (code === LIMIT_REACHED) return { action: 'person' };
+  if (code !== QUOTA_EXHAUSTED) return { action: 'failed' };
+  const data = own(error, 'data');
+  if (!quotaDataOk(data)) return { action: 'invalid' };
+  if (!data.retryable) return { action: 'person' };
+  return data.resetsAt !== undefined && utcTime(data.resetsAt) > at ? { action: 'resend', notBefore: data.resetsAt } : { action: 'resend' };
+}
+
+/** The idempotency key of an intent {agentId, capability, input, request?}: a UUID of version 8 over its RFC 8785 form. */
+export function intentIdempotencyKey(intent) {
+  const names = ['agentId', 'capability', 'input', 'request'];
+  if (!isObject(intent) || Object.keys(intent).some((name) => !names.includes(name))) return undefined;
+  const [agentId, capability, input, request] = names.map((name) => own(intent, name));
+  if (!isString(agentId) || agentId.length === 0 || !isString(capability) || capability.length === 0 || !isObject(input)) return undefined;
+  if (Object.hasOwn(intent, 'request') && (!isString(request) || request.length === 0 || codePoints(request) > 256)) return undefined;
+  let form;
+  try {
+    form = jcs(Object.hasOwn(intent, 'request') ? { agentId, capability, input, request } : { agentId, capability, input });
+  } catch {
+    return undefined;
+  }
+  const bytes = crypto.createHash('sha256').update(form, 'utf8').digest().subarray(0, 16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x80;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function readsNullUsage(requestMeta) {
+  const protocols = own(requestMeta, 'protocols');
+  return Array.isArray(protocols) && protocols.includes(INTEROP_NULL_USAGE);
+}
+
+/** A request's `_meta` from this kit as a caller: its trace, and the interop revisions it reads (DEC-0087). */
+export function requestMeta(traceparent) {
+  const meta = { protocols: [...PROTOCOLS_READ] };
+  if (parseTraceparent(traceparent)) meta.traceparent = traceparent;
+  return meta;
+}
+
+/** FAC-SEM-119 on a usage: partial false asserts every number known, so it stands beside no null. */
+export function usageFindings(usage, at) {
+  if (!isObject(usage) || usage.partial !== false) return [];
+  const unknown = USAGE_KEYS.filter((name) => Object.hasOwn(usage, name) && usage[name] === null);
+  if (unknown.length === 0) return [];
+  return [{ code: 'FAC-SEM-119', instancePath: `${at}/partial`, message: `partial is false while ${unknown.join(', ')} is null: an unknown number makes the usage partial` }];
+}
+
+/** The usage a provider writes toward a caller: null and partial toward a 0.2 reader, the measured lower bound otherwise. */
+export function usageToward(usage, meta) {
+  if (readsNullUsage(meta)) {
+    const checked = checkUsage(usage, true);
+    if (USAGE_KEYS.some((name) => checked[name] === null) && !('partial' in checked)) checked.partial = true;
+    return checked;
+  }
+  if (!isObject(usage)) throw new InteropError('usage must be an object.');
+  return checkUsage(Object.fromEntries(Object.entries(usage).filter(([key]) => key !== 'partial').map(([key, value]) => [key, value === null ? 0 : value])));
+}
+
+function jobFindings(value) {
+  const findings = [];
+  if ('malformed' in readJobPause(value)) {
+    findings.push({ code: 'FAC-SEM-119', instancePath: '/job/statusMessage', message: "a working job's message that starts quota-exhausted reads `quota-exhausted`, `quota-exhausted until <UTC instant>`, then optionally `: <text>`, at most 500 characters" });
+  }
+  const error = own(own(value, 'job'), 'error');
+  const data = own(error, 'data');
+  if (own(error, 'code') === QUOTA_EXHAUSTED && isString(own(data, 'resetsAt')) && !Number.isFinite(utcTime(own(data, 'resetsAt')))) {
+    findings.push({ code: 'FAC-SEM-119', instancePath: '/job/error/data/resetsAt', message: 'resetsAt is a UTC instant on a day that exists' });
+  }
+  findings.push(...usageFindings(own(own(own(value, 'job'), 'result'), 'usage'), '/job/result/usage'));
+  return findings;
+}
+
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** FAC-SEM-119 (kinds interop-job, usage and result) and FAC-SEM-120 (kind job-caller); undefined for another kind. */
+export function jobLimitRules(kind, value) {
+  if (kind === 'interop-job') return jobFindings(value);
+  if (kind === 'usage') return usageFindings(value, '');
+  if (kind === 'result') return usageFindings(own(value, 'usage'), '/usage');
+  if (kind === 'job-caller') {
+    const expected = jobCallerAction(own(value, 'answer'), own(value, 'now'));
+    return sameJson(own(value, 'action'), expected) ? [] : [{ code: 'FAC-SEM-120', instancePath: '/action', message: `the caller answers ${JSON.stringify(expected)} as jobCallerAction does` }];
+  }
+  return undefined;
+}
+
+/** A paused job's statusMessage in the pause grammar; throws InteropError for one a reader would call malformed. */
+export function pauseMessage({ resetsAt, text } = {}) {
+  const message = `${QUOTA_EXHAUSTED}${resetsAt === undefined ? '' : ` until ${resetsAt}`}${text === undefined ? '' : `: ${text}`}`;
+  if ('malformed' in readJobPause({ job: { id: 'x', status: 'working', statusMessage: message } })) {
+    throw new InteropError('A pause reads quota-exhausted [until <UTC instant, Z, at most 3 fraction digits>][: <text>], at most 500 characters.');
+  }
+  return message;
+}
+
+/** The provider's answer to a repeated key: 'run' (the intent runs again, once) or 'same' (answer with that job). */
+export function repeatedKeyDecision(job, now, { limitHolds, approvalGranted = false } = {}) {
+  if (!isObject(job) || job.status !== 'failed') return 'same';
+  const error = own(job, 'error');
+  const code = own(error, 'code');
+  if (code === LIMIT_REACHED) return approvalGranted === true ? 'run' : 'same';
+  if (code !== QUOTA_EXHAUSTED) return 'same';
+  if (limitHolds !== undefined && limitHolds !== null) return limitHolds === false ? 'run' : 'same';
+  const data = own(error, 'data');
+  const at = utcTime(now);
+  if (!quotaDataOk(data) || !data.retryable || !Number.isFinite(at)) return 'same';
+  return data.resetsAt === undefined || utcTime(data.resetsAt) <= at ? 'run' : 'same';
+}
+// #endregion job-limits-kit-node
+
 // --- C3.3 awaiting a choice ------------------------------------------------------------------
 export function formRequest(message, properties, required) {
   for (const [field, schema] of Object.entries(properties)) {
@@ -167,14 +368,40 @@ export class JobStore {
     return { ...record.job };
   }
 
-  create(capability, input, { traceparent, pollIntervalMs } = {}) {
+  // With idempotencyKey the key is kept per caller (the authenticated caller, DEC-0087): a key that already names a job
+  // starts nothing and throws, unless repeat() answers 'run'; then the key names the new job.
+  create(capability, input, { traceparent, pollIntervalMs, caller = null, idempotencyKey, now, limitHolds, approvalGranted = false } = {}) {
+    if (idempotencyKey !== undefined) {
+      const decision = this.repeat(caller, idempotencyKey, now ?? nowIso(), { limitHolds, approvalGranted });
+      if (decision.decision === 'same') throw new InteropError(`Key ${idempotencyKey} already names job ${decision.job.id}; answer with that job (JobStore.repeat).`);
+    }
     const id = `job_${crypto.randomBytes(12).toString('hex')}`;
     const job = { id, status: 'working' };
     if (pollIntervalMs) job.pollIntervalMs = Math.trunc(pollIntervalMs);
     this.save({ job, private: { capability, input, traceparent: parseTraceparent(traceparent) ? traceparent : null } });
+    if (idempotencyKey !== undefined) atomicWrite(this.keyFile(caller, idempotencyKey), `${JSON.stringify({ job: id })}\n`, 0o600);
     return { job: { id, status: 'working' } };
   }
 
+  keyFile(caller, key) {
+    if (typeof key !== 'string' || key.length === 0) throw new InteropError('An idempotency key is a non-empty string.');
+    const dir = path.join(this.dir, 'keys');
+    ensurePrivateDir(dir);
+    return path.join(dir, `${crypto.createHash('sha256').update(JSON.stringify([caller ?? null, key]), 'utf8').digest('hex')}.json`);
+  }
+
+  // The answer to a key this caller sent before: {decision: 'new'|'same'|'run', job}.
+  repeat(caller, key, now, options = {}) {
+    let id;
+    try { id = JSON.parse(fs.readFileSync(this.keyFile(caller, key), 'utf8')).job; } catch (e) {
+      if (e.code === 'ENOENT') return { decision: 'new', job: null };
+      throw new InteropError(`Key ${key} is unreadable on disk.`);
+    }
+    let job;
+    try { job = this.get(id); } catch (e) { if (e instanceof UnknownJob) return { decision: 'new', job: null }; throw e; }
+    return { decision: repeatedKeyDecision(job, now, options), job };
+  }
+
   get(jobId) { return { ...this.load(jobId).job }; }
   traceparent(jobId) { return this.load(jobId).private.traceparent ?? null; }
 
@@ -216,7 +443,27 @@ export class JobStore {
     return this.transition(jobId, 'completed', { result });
   }
 
-  fail(jobId, code, message) { return this.transition(jobId, 'failed', { error: { code, message } }); }
+  fail(jobId, code, message, data) { return this.transition(jobId, 'failed', { error: data === undefined || data === null ? { code, message } : { code, message, data } }); }
+
+  // A job a limit paused and its provider will resume: working, the pause grammar, pollIntervalMs reaching the reset.
+  pause(jobId, { resetsAt, text } = {}) {
+    const statusMessage = pauseMessage({ resetsAt, text });
+    if (resetsAt !== undefined) {
+      const wait = utcTime(resetsAt) - Date.now();
+      if (wait > 0) { const record = this.load(jobId); record.job.pollIntervalMs = Math.trunc(Math.min(wait, 3600000)); this.save(record); }
+    }
+    return this.transition(jobId, 'working', { statusMessage });
+  }
+
+  // A job a limit stopped and its provider will not resume: failed, quota-exhausted, data {retryable, resetsAt?}.
+  quotaExhausted(jobId, message, { retryable, resetsAt } = {}) {
+    const data = resetsAt === undefined ? { retryable } : { retryable, resetsAt };
+    if (!quotaDataOk(data)) throw new InteropError('quota-exhausted data is {retryable: boolean, resetsAt?: UTC instant}, resetsAt only with retryable true.');
+    return this.fail(jobId, QUOTA_EXHAUSTED, message, data);
+  }
+
+  // A job whose effect may have happened: failed, outcome-unknown; its key never runs again.
+  outcomeUnknown(jobId, message, data) { return this.fail(jobId, OUTCOME_UNKNOWN, message, data); }
   cancel(jobId) { return this.transition(jobId, 'cancelled'); }
 }
 // #endregion interop-kit-node

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-profiles.mjs

@@ -367,10 +367,11 @@ function routeEvent(value) {
   });
   const expectProbes = (count) => {
     const indexes = probes.map(indexOf);
-    const expected = Array.from({ length: Math.max(count, 0) }, (_, index) => index);
-    if (indexes.length !== expected.length || indexes.some((index, position) => index !== expected[position])) {
-      wrong('/probes', `the walk must record candidates ${expected.join(', ') || 'none'} in order; it records ${indexes.join(', ') || 'none'}`);
-    }
+    // Compared with 0…count−1 before any list is built, and the message lists at most 64 candidates, so a count from an
+    // index of 2**32 allocates nothing and never throws (contract route-rules.ts at DEC-0084, from this kit's report).
+    if (indexes.length === count && indexes.every((index, position) => index === position)) return;
+    const expected = count <= 64 ? Array.from({ length: count }, (_, index) => index).join(', ') || 'none' : `0 to ${count - 1}`;
+    wrong('/probes', `the walk must record candidates ${expected} in order; it records ${indexes.join(', ') || 'none'}`);
   };
   if (event.kind === 'runner-exhausted') {
     expectProbes(list.length);

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-service.mjs

@@ -862,12 +862,13 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
 
 /** Each contract protocol's published revisions, oldest first (the contract's `PROTOCOL_REVISIONS`); a test holds it equal to the contract's. */
 export const PROTOCOL_REVISIONS = new Map(Object.entries({
-  'access-log': ['1'], approval: ['1'], 'activity-summary': ['1'], 'estate-record': ['1'], 'execution-packet': ['1'],
+  'access-log': ['1'], approval: ['1'], 'activity-summary': ['1'], 'enroll-token': ['1'], entitlement: ['1'], 'entitlement-key-set': ['1'], 'estate-record': ['1'], 'execution-packet': ['1'],
   'fabric-activity': ['0.1'], 'fabric-dashboard': ['0.1'], 'fabric-delegation': ['0.1'], 'fabric-device': ['0.1'],
-  'fabric-interop': ['0.1'], 'fabric-local-channel': ['0.1'], 'fabric-local-runner': ['0.1'], 'fabric-operator-channel': ['0.1'],
+  'fabric-interop': ['0.1', '0.2'], 'fabric-local-channel': ['0.1'], 'fabric-local-runner': ['0.1'], 'fabric-operator-channel': ['0.1'],
   'fabric-package': ['1'], 'fabric-project-comms': ['0.1'], 'fabric-proposal': ['1'], 'fabric-provider': ['0.1'], 'fabric-relay': ['0.1'],
   'fabric-secret-envelope': ['1'], 'fabric-service': ['0.1'], 'fabric-settings-backup': ['1'], heartbeat: ['1'], 'learning-note': ['1'],
-  memory: ['0.1'], pipeline: ['0.1'], 'revocation-delta': ['1'], 'session-handoff': ['1'], 'window-lease': ['1'],
+  memory: ['0.1'], 'pairing-message': ['1'], pipeline: ['0.1'], 'revocation-delta': ['1'], 'session-handoff': ['1'],
+  'share-registration': ['1'], 'share-registration-receipt': ['1'], 'window-lease': ['1'],
 }));
 export const MAX_PROTOCOLS = 64;
 const REVISION = /^([a-z][a-z0-9.-]{0,63})\/([0-9]{1,4}(?:\.[0-9]{1,4}){0,2})$/;

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-share.mjs

@@ -0,0 +1,109 @@
+// Share grants into an organization and their registrations (contract DEC-0086), the Node kit; the twin of
+// fabric_share.py, answer for answer (test/fixtures/contract/share-vectors.json). Node built-ins only.
+// FAC-SEM-117 (a share grant's id, window and agentRef, with parent), FAC-SEM-118 (a share-registration/1 document) and
+// FAC-SEM-045's DEC-0086 clause (a grant.usage carries its grant's own org: context). Deriving, deciding and joining
+// registrations belong to the sharer's node and the organization server, not to this kit. Every function answers and
+// never throws on malformed input. Normative source: the contract's src/share-registration.ts.
+// #region share-kit-node, docs: plugins/fabric-agent-adapter/skills/building-fabric-services/references/estate-record.md#share-grants-into-an-organization
+
+import { estateTime, grantContextFindings } from './fabric-estate.mjs';
+import { sameIdentifier } from './fabric-identifiers.mjs';
+
+export const SHARE_REGISTRATION_TYPE = 'share-registration/1';
+export const SHARE_REGISTRATION_RECEIPT_TYPE = 'share-registration-receipt/1';
+export const SHARE_GRANT_ID = /^urn:fabric:share:(?!0{32}$)[0-9a-f]{32}$/;
+export const ORG_CONTEXT = /^org:[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const INSTANT = /^[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-5][0-9](?:\.[0-9]{1,3})?(?:[Zz]|[+-][0-9]{2}:[0-9]{2})$/;
+const SUB_MILLISECOND = /:[0-9]{2}\.[0-9]{4,}/;
+
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isString = (value) => typeof value === 'string';
+const list = (value) => (Array.isArray(value) ? value.filter(isObject) : []);
+const indexed = (value) => (Array.isArray(value) ? value.flatMap((item, index) => (isObject(item) ? [[item, index]] : [])) : []);
+const show = (value) => {
+  if (typeof value === 'string') return value;
+  try { return String(value); } catch { return JSON.stringify(value) ?? typeof value; }
+};
+const finding = (code, instancePath, message) => ({ code, instancePath, message });
+const isOrg = (value) => isString(value) && value.startsWith('org:');
+
+export const isShareGrantId = (value) => isString(value) && SHARE_GRANT_ID.test(value);
+export const isOrgContext = (value) => isString(value) && ORG_CONTEXT.test(value);
+
+/** FAC-SEM-117 on one grant: an organization's share grant has a share grant id and a millisecond window. */
+export function shareGrantIdFindings(grant, at) {
+  if (!isObject(grant) || !isOrg(grant.context)) return [];
+  const findings = [];
+  const id = isObject(grant.meta) ? grant.meta.id : undefined;
+  if (!isShareGrantId(id)) findings.push(finding('FAC-SEM-117', `${at}/meta/id`, 'a share grant into an organization is named urn:fabric:share: and 32 lower-case hex digits from a CSPRNG, never a name, an address or an estate id'));
+  for (const name of ['startsAt', 'expiresAt']) {
+    if (isString(grant[name]) && SUB_MILLISECOND.test(grant[name])) findings.push(finding('FAC-SEM-117', `${at}/${name}`, 'a share grant into an organization carries its window with at most three fraction digits'));
+  }
+  return findings;
+}
+
+/** Kind grant as the contract's contextRules answers it: FAC-SEM-110 (DEC-0082), then FAC-SEM-117 (DEC-0086). */
+export const grantFindings = (grant, at = '') => [...grantContextFindings(grant, at), ...shareGrantIdFindings(grant, at)];
+
+function agentsUnder(record, context, id) {
+  const placements = list(record.machines).flatMap((machine) => list(machine.packages));
+  return new Set(placements.filter((p) => p.context === context && isString(id) && sameIdentifier(p.grant, id)).map((p) => show(p.agentRef)));
+}
+
+/** FAC-SEM-117 on a record {record, parent?}: id and window, one agentRef, and the same agentRef as in parent. */
+export function orgShareGrantsFindings(value) {
+  const record = isObject(value) && isObject(value.record) ? value.record : {};
+  const parent = isObject(value) && isObject(value.parent) ? value.parent : undefined;
+  const findings = [];
+  for (const [grant, index] of indexed(record.shareGrants)) {
+    const at = `/record/shareGrants/${index}`;
+    findings.push(...shareGrantIdFindings(grant, at));
+    if (!isOrg(grant.context)) continue;
+    const id = isObject(grant.meta) ? grant.meta.id : undefined;
+    const refs = agentsUnder(record, grant.context, id);
+    if (refs.size > 1) findings.push(finding('FAC-SEM-117', at, `the placements naming this grant run ${refs.size} agents: a share grant into an organization runs one agentRef`));
+    if (!parent) continue;
+    const before = list(parent.shareGrants).find((old) => old.context === grant.context && isObject(old.meta) && isString(id) && sameIdentifier(old.meta.id, id));
+    const earlier = before ? agentsUnder(parent, before.context, id) : new Set();
+    if (earlier.size > 0 && [...refs].some((ref) => !earlier.has(ref))) {
+      findings.push(finding('FAC-SEM-117', at, 'this grant ran another agent in the earlier revision given as parent: a share grant into an organization keeps its agentRef; move the share by revoking it and minting a new id'));
+    }
+  }
+  return findings;
+}
+
+const time = (value) => (isString(value) && INSTANT.test(value) ? estateTime(value) : Number.NaN);
+
+/** FAC-SEM-118 on one share-registration/1 document. */
+export function registrationFindings(value) {
+  if (!isObject(value) || value.type !== SHARE_REGISTRATION_TYPE) return [];
+  const names = value.state === 'active' ? ['startsAt', 'expiresAt'] : ['withdrawnAt'];
+  const unreadable = names.filter((name) => !Number.isFinite(time(value[name])));
+  const findings = unreadable.map((name) => finding('FAC-SEM-118', `/${name}`, 'an instant is an RFC 3339 date-time with an offset, on a day that exists, with at most three fraction digits'));
+  if (value.state === 'active' && !unreadable.length && time(value.startsAt) >= time(value.expiresAt)) findings.push(finding('FAC-SEM-118', '/expiresAt', "an active registration's window ends after it starts"));
+  return findings;
+}
+
+/** FAC-SEM-045's DEC-0086 clause on {binding, batch}: a grant.usage carries org: and the certificate's org.id as written. */
+export function grantUsageContextFindings(value) {
+  const binding = isObject(value) && isObject(value.binding) ? value.binding : {};
+  const org = isObject(binding.org) ? binding.org.id : undefined;
+  const batch = isObject(value) && isObject(value.batch) ? value.batch : {};
+  const findings = [];
+  list(batch.events).forEach((event, i) => {
+    if (event.kind !== 'grant.usage') return;
+    const context = isObject(event.data) ? event.data.context : undefined;
+    if (typeof org !== 'string' || context !== `org:${org}`) findings.push(finding('FAC-SEM-045', `/batch/events/${i}/data/context`, "a grant's usage carries its grant's own context, org: and the client certificate's org.id; another organization's is refused as attribution"));
+  });
+  return findings;
+}
+
+/** Kinds grant, org-share-grants, share-registration and device-attribution (045's grant.usage clause); undefined otherwise. */
+export function shareRules(kind, value) {
+  if (kind === 'grant') return grantFindings(value, '');
+  if (kind === 'org-share-grants') return orgShareGrantsFindings(value);
+  if (kind === 'share-registration') return registrationFindings(value);
+  if (kind === 'device-attribution') return grantUsageContextFindings(value);
+  return undefined;
+}
+// #endregion share-kit-node