@forgeax/engine-pack 0.0.0-dev.8d955ade1c79

package/src/producer-contract.ts

@@ -0,0 +1,277 @@
+import type {
+  AssetSubjectRef,
+  ImportedOutputDeclaration,
+  ProducerContractDiagnostic,
+  ProducerContractResult,
+  SourceOverrideMap,
+} from '@forgeax/engine-types';
+import { validateSourceOverrideMap } from '@forgeax/engine-types';
+
+type ProducerObject = Record<string, unknown>;
+
+function isRecord(value: unknown): value is ProducerObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasText(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function issue(
+  code: ProducerContractDiagnostic['code'],
+  subjectId: string,
+  expected: string,
+  hint: string,
+  actual?: string,
+  authority: 'producer' | 'pack' = 'producer',
+): ProducerContractResult<never> {
+  const subject: AssetSubjectRef = { type: 'asset', id: subjectId };
+  return {
+    ok: false,
+    error: {
+      code,
+      subject,
+      expected,
+      ...(actual === undefined ? {} : { actual }),
+      hint,
+      authority,
+    },
+  };
+}
+
+function validateFacts(
+  value: ProducerObject,
+  subjectId: string,
+): ProducerContractResult<ProducerObject> {
+  if ('packageId' in value && !hasText(value.packageId)) {
+    return issue(
+      'invalid-producer-fact',
+      subjectId,
+      'packageId must be a non-empty string',
+      'publish a stable package identity',
+    );
+  }
+  if ('provenance' in value) {
+    const provenance = value.provenance;
+    if (!isRecord(provenance) || !hasText(provenance.provider) || !hasText(provenance.version)) {
+      return issue(
+        'invalid-producer-fact',
+        subjectId,
+        'provenance.provider and provenance.version must be non-empty',
+        'publish provider identity and version',
+      );
+    }
+  }
+  if ('revision' in value) {
+    const revision = value.revision;
+    if (
+      !isRecord(revision) ||
+      !hasText(revision.digest) ||
+      !hasText(revision.rootId) ||
+      typeof revision.observedAt !== 'number' ||
+      !Number.isFinite(revision.observedAt)
+    ) {
+      return issue(
+        'invalid-producer-fact',
+        subjectId,
+        'revision.digest, revision.rootId and finite revision.observedAt',
+        'publish a complete resource revision',
+      );
+    }
+  }
+  if ('diagnostics' in value) {
+    if (!Array.isArray(value.diagnostics)) {
+      return issue(
+        'invalid-producer-fact',
+        subjectId,
+        'diagnostics must be an array',
+        'publish structured diagnostics as an array',
+      );
+    }
+    for (const diagnostic of value.diagnostics) {
+      if (!isRecord(diagnostic) || !hasText(diagnostic.code)) {
+        return issue(
+          'invalid-producer-fact',
+          subjectId,
+          'each diagnostic needs a stable code',
+          'publish a machine-readable diagnostic code',
+        );
+      }
+      if (diagnostic.severity === 'blocking') {
+        if (!isRecord(diagnostic.subject) || !hasText(diagnostic.subject.id)) {
+          return issue(
+            'invalid-producer-fact',
+            subjectId,
+            'blocking diagnostic.subject must identify an object',
+            'set subject.type and subject.id',
+          );
+        }
+        if (!hasText(diagnostic.expected) || !hasText(diagnostic.hint)) {
+          return issue(
+            'invalid-producer-fact',
+            subjectId,
+            'blocking diagnostics need expected and hint',
+            'provide an executable recovery hint',
+          );
+        }
+      }
+    }
+  }
+  return { ok: true, value };
+}
+
+function validateMetaSourceOverrides(
+  value: ProducerObject,
+  subjectId: string,
+): ProducerContractResult<ProducerObject> {
+  if (!('sourceOverrides' in value)) return { ok: true, value };
+  const declaredSourceKeys = Array.isArray(value.subAssets)
+    ? value.subAssets.flatMap((subAsset) =>
+        isRecord(subAsset) && hasText(subAsset.sourceKey) ? [subAsset.sourceKey] : [],
+      )
+    : [];
+  const result = validateSourceOverrideMap(value.sourceOverrides, declaredSourceKeys);
+  if (!result.ok) {
+    return issue(
+      result.error.code,
+      subjectId,
+      result.error.expected,
+      result.error.hint,
+      result.error.actual,
+      'pack',
+    );
+  }
+  return {
+    ok: true,
+    value: { ...value, sourceOverrides: result.value as SourceOverrideMap | undefined },
+  };
+}
+
+/**
+ * Validate one package or imported-output producer declaration.
+ *
+ * The accepted fields mirror the engine-types POD contract. This function
+ * validates that schema without creating a second schema or interpreting
+ * diagnostic messages.
+ */
+export function validateProducerContract(value: unknown): ProducerContractResult<ProducerObject> {
+  if (!isRecord(value)) {
+    return issue(
+      'invalid-producer-fact',
+      'unknown',
+      'producer declaration must be an object',
+      'publish a JSON object',
+    );
+  }
+
+  const subjectId = hasText(value.guid)
+    ? value.guid
+    : hasText(value.packageId)
+      ? value.packageId
+      : 'unknown';
+  const facts = validateFacts(value, subjectId);
+  if (!facts.ok) return facts;
+
+  const metaOverrides = validateMetaSourceOverrides(value, subjectId);
+  if (!metaOverrides.ok) return metaOverrides;
+
+  if ('kind' in value && !hasText(value.kind)) {
+    return issue(
+      'invalid-producer-fact',
+      subjectId,
+      'kind must be a non-empty open string',
+      'publish the provider-owned asset kind',
+    );
+  }
+  if ('execution' in value && value.execution !== 'direct' && value.execution !== 'cooked') {
+    return issue(
+      'invalid-producer-fact',
+      subjectId,
+      'execution must be either direct or cooked',
+      'publish the explicit authoring execution mode',
+    );
+  }
+  const hasOutputIdentity = 'kind' in value || 'sourceIndex' in value || 'sourceKey' in value;
+  if (!hasOutputIdentity) return facts;
+  if (value.sourceKey !== undefined && !hasText(value.sourceKey)) {
+    return issue(
+      'invalid-source-key',
+      subjectId,
+      'sourceKey must be a non-empty producer-owned string',
+      'publish a stable semantic sourceKey',
+    );
+  }
+  if (
+    value.sourceIndex !== undefined &&
+    (typeof value.sourceIndex !== 'number' ||
+      !Number.isInteger(value.sourceIndex) ||
+      value.sourceIndex < 0)
+  ) {
+    return issue(
+      'invalid-source-index',
+      subjectId,
+      'sourceIndex must be a non-negative integer locator',
+      'publish a non-negative sourceIndex without using it as identity',
+    );
+  }
+  if (value.sourceKey === undefined && value.sourceIndex !== undefined) {
+    return issue(
+      'missing-source-key',
+      subjectId,
+      'sourceKey is required when an output declares sourceIndex',
+      'publish a stable semantic key; do not derive identity from sourceIndex',
+    );
+  }
+  if (
+    'compatiblePreviousKinds' in value &&
+    (!Array.isArray(value.compatiblePreviousKinds) ||
+      value.compatiblePreviousKinds.some((kind) => !hasText(kind)))
+  ) {
+    return issue(
+      'invalid-producer-fact',
+      subjectId,
+      'compatiblePreviousKinds must be an array of non-empty kind strings',
+      'declare only producer-verified prior kinds that may preserve the GUID',
+    );
+  }
+  return metaOverrides;
+}
+
+/**
+ * Validate output topology without ever treating `sourceIndex` as identity.
+ *
+ * AI-readable callers should use the discriminated result and its structured
+ * `code`, `expected`, `actual`, and `hint` fields for recovery decisions.
+ */
+export function validateProducerOutputs(
+  outputs: readonly ImportedOutputDeclaration[],
+): ProducerContractResult<readonly ImportedOutputDeclaration[]> {
+  const missingKey = outputs.find((output) => output.sourceKey === undefined);
+  if (missingKey !== undefined) {
+    return issue(
+      outputs.length > 1 ? 'source-index-ambiguous' : 'missing-source-key',
+      missingKey.guid,
+      'every output declaration needs a stable sourceKey',
+      'add sourceKey to each output before matching topology',
+    );
+  }
+  const keys = new Map<string, ImportedOutputDeclaration>();
+  for (const output of outputs) {
+    const result = validateProducerContract(output);
+    if (!result.ok) return result;
+    const sourceKey = output.sourceKey;
+    if (sourceKey === undefined) continue;
+    const prior = keys.get(sourceKey);
+    if (prior !== undefined) {
+      return issue(
+        'duplicate-source-key',
+        output.guid,
+        'sourceKey values must be unique within one producer package',
+        'rename the duplicate semantic output key',
+        sourceKey,
+      );
+    }
+    keys.set(sourceKey, output);
+  }
+  return { ok: true, value: outputs };
+}

package/src/resolve-asset-source.ts

@@ -0,0 +1,88 @@
+import { dirname, posix, resolve } from 'node:path';
+import type { Result } from '@forgeax/engine-types';
+import { PACK_ERROR_HINTS, err as resultErr, ok as resultOk } from '@forgeax/engine-types';
+import { deriveAssetName } from './deriveAssetName.js';
+import { PackError } from './errors.js';
+
+function deriveSourceName(metaFileName: string): string {
+  return metaFileName.replace(/\.meta\.json$/, '');
+}
+
+const PATH_REF_RE = /^@([^/]+)\/(.+)$/;
+
+function isPathEscape(pathDir: string, resolved: string): boolean {
+  const rel = posix.relative(pathDir, resolved);
+  return rel.startsWith('..') || posix.isAbsolute(rel);
+}
+
+export function resolveAssetSource(
+  metaPath: string,
+  source: string | undefined,
+  paths: Record<string, string>,
+): Result<string, PackError> {
+  if (source === undefined) {
+    const metaDir = dirname(metaPath);
+    const metaName = deriveAssetName(metaPath, 1);
+    const derived = deriveSourceName(metaName);
+    return resultOk(resolve(metaDir, derived));
+  }
+
+  if (source.startsWith('@')) {
+    const match = source.match(PATH_REF_RE);
+    if (!match) {
+      return resultErr(
+        new PackError({
+          code: 'pack-malformed-path-ref',
+          expected: 'source in format @<name>/<rest>',
+          hint: PACK_ERROR_HINTS['pack-malformed-path-ref'],
+          detail: {
+            code: 'pack-malformed-path-ref',
+            reason: 'format',
+            rawSource: source,
+            expectedFormat: '@<name>/<rest>',
+          },
+        }),
+      );
+    }
+
+    const [, name, rest] = match as [string, string, string];
+    const pathDir = paths[name];
+
+    if (pathDir === undefined) {
+      return resultErr(
+        new PackError({
+          code: 'pack-unknown-path',
+          expected: 'path name found in package.json#forgeax.assets.paths',
+          hint: PACK_ERROR_HINTS['pack-unknown-path'],
+          detail: {
+            code: 'pack-unknown-path',
+            pathName: name,
+            knownNames: Object.keys(paths),
+          },
+        }),
+      );
+    }
+
+    const resolved = resolve(pathDir, rest);
+
+    if (isPathEscape(pathDir, resolved)) {
+      return resultErr(
+        new PackError({
+          code: 'pack-malformed-path-ref',
+          expected: 'rest path must not escape the declared path directory',
+          hint: PACK_ERROR_HINTS['pack-malformed-path-ref'],
+          detail: {
+            code: 'pack-malformed-path-ref',
+            reason: 'escape',
+            rawSource: source,
+            expectedFormat: '@<name>/<rest>',
+          },
+        }),
+      );
+    }
+
+    return resultOk(resolved);
+  }
+
+  return resultOk(resolve(dirname(metaPath), source));
+}

package/src/runtime-projection.ts

@@ -0,0 +1,100 @@
+import type {
+  AssetEnvelopeV2,
+  AssetPublicationTuple,
+  AssetRuntimeArtifactDescriptor,
+  PackV2,
+  PackV2Error,
+  Result,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+
+export interface RuntimeAssetProjectionInput<P = unknown> {
+  readonly guid: string;
+  readonly kind: string;
+  readonly payload: P;
+  readonly refs: readonly string[];
+  readonly artifacts: Readonly<Record<string, AssetRuntimeArtifactDescriptor>>;
+}
+
+export interface RuntimePackProjectionInput<P = unknown> extends AssetPublicationTuple {
+  readonly assets: readonly RuntimeAssetProjectionInput<P>[];
+}
+
+function invalid(observed: string, expected: string): Result<never, PackV2Error> {
+  return err({
+    code: 'pack-v2-envelope-invalid',
+    expected,
+    hint: 'publish one verified Pack v2 envelope with one atomic publication tuple',
+    detail: { observed, expected },
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isTuple(value: unknown): value is AssetPublicationTuple {
+  return (
+    isRecord(value) &&
+    typeof value.scopeId === 'string' &&
+    value.scopeId.length > 0 &&
+    typeof value.generation === 'number' &&
+    Number.isInteger(value.generation) &&
+    value.generation > 0 &&
+    typeof value.digest === 'string' &&
+    value.digest.length > 0 &&
+    typeof value.outputSetDigest === 'string' &&
+    value.outputSetDigest.length > 0
+  );
+}
+
+function isAsset(value: unknown): value is RuntimeAssetProjectionInput {
+  return (
+    isRecord(value) &&
+    typeof value.guid === 'string' &&
+    value.guid.length > 0 &&
+    typeof value.kind === 'string' &&
+    value.kind.length > 0 &&
+    Array.isArray(value.refs) &&
+    value.refs.every((ref) => typeof ref === 'string') &&
+    isRecord(value.artifacts)
+  );
+}
+
+/** Project producer facts into the only runtime Pack v2 envelope. */
+export function projectRuntimePack<P = unknown>(value: unknown): Result<PackV2<P>, PackV2Error> {
+  if (
+    !isRecord(value) ||
+    (('schemaVersion' in value || 'kind' in value) &&
+      (value.schemaVersion !== '2.0.0' || value.kind !== 'internal-text-package'))
+  ) {
+    return invalid('legacy or malformed pack input', 'runtime Pack v2');
+  }
+  if (!isTuple(value) || !Array.isArray(value.assets) || !value.assets.every(isAsset)) {
+    return invalid('incomplete publication tuple or asset envelope', 'verified runtime Pack v2');
+  }
+
+  const seen = new Set<string>();
+  for (const asset of value.assets) {
+    const guid = asset.guid.toLowerCase();
+    if (seen.has(guid)) {
+      return err({
+        code: 'pack-v2-duplicate-guid',
+        expected: 'one asset envelope per GUID',
+        hint: 'publish one producer row and recook the package output set',
+        detail: { guid: asset.guid, paths: [] },
+      });
+    }
+    seen.add(guid);
+  }
+
+  return ok({
+    schemaVersion: '2.0.0',
+    kind: 'internal-text-package',
+    scopeId: value.scopeId,
+    generation: value.generation,
+    digest: value.digest,
+    outputSetDigest: value.outputSetDigest,
+    assets: value.assets as readonly AssetEnvelopeV2<P>[],
+  });
+}

package/src/runtime-publication.ts

@@ -0,0 +1,190 @@
+import { createHash } from 'node:crypto';
+import type {
+  AssetPublicationEnvelope,
+  AssetPublicationExternalEvidence,
+  AssetPublicationOutput,
+} from '@forgeax/engine-types';
+
+export interface RuntimePackAssetInput {
+  readonly guid: string;
+  readonly kind: string;
+  readonly name?: string;
+  readonly payload: unknown;
+  readonly refs?: readonly string[];
+  readonly artifacts?: Readonly<Record<string, unknown>>;
+}
+
+export interface RuntimePackInput {
+  readonly assets: readonly RuntimePackAssetInput[];
+}
+
+export interface RuntimePackEnvelope {
+  readonly schemaVersion: '2.0.0';
+  readonly kind: 'internal-text-package';
+  readonly scopeId: string;
+  readonly generation: number;
+  readonly digest: string;
+  readonly outputSetDigest: string;
+  readonly assets: readonly RuntimePackAsset[];
+}
+
+export interface RuntimePackPublication {
+  readonly pack: RuntimePackEnvelope;
+  readonly publication: AssetPublicationEnvelope;
+}
+
+interface RuntimePackAsset extends RuntimePackAssetInput {
+  readonly refs: readonly string[];
+  readonly artifacts: Readonly<Record<string, unknown>>;
+}
+
+export interface RuntimePackPublicationInput {
+  readonly pack: RuntimePackInput;
+  readonly scopeId: string;
+  readonly sourcePath: string;
+  readonly sourceRevision: string;
+  readonly packageUrl: string;
+  readonly inputFingerprint?: string;
+  readonly digest?: string;
+  readonly generation?: number;
+  readonly outputs?: readonly AssetPublicationOutput[];
+  readonly externalEvidence?: readonly AssetPublicationExternalEvidence[];
+}
+
+function stable(value: unknown): string {
+  if (value instanceof Uint8Array) return `bytes:${Buffer.from(value).toString('base64')}`;
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stable(record[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+function digest(value: unknown): string {
+  return `sha256:${createHash('sha256').update(stable(value)).digest('hex')}`;
+}
+
+function normalizedAssets(pack: RuntimePackInput): readonly RuntimePackAsset[] {
+  return pack.assets.map((asset) => {
+    const payload = asset.payload;
+    const canonicalPayload =
+      payload !== null &&
+      typeof payload === 'object' &&
+      !Array.isArray(payload) &&
+      !(payload instanceof Uint8Array) &&
+      typeof (payload as Record<string, unknown>).kind !== 'string'
+        ? { ...(payload as Record<string, unknown>), kind: asset.kind }
+        : payload;
+    return {
+      ...asset,
+      payload: canonicalPayload,
+      refs: [...(asset.refs ?? [])].map((ref) => ref.toLowerCase()),
+      artifacts: asset.artifacts ?? {},
+    };
+  });
+}
+
+function outputFor(asset: RuntimePackAsset): AssetPublicationOutput {
+  return {
+    guid: asset.guid.toLowerCase(),
+    sourceKey: asset.guid.toLowerCase(),
+    kind: asset.kind,
+    digest: digest({
+      guid: asset.guid.toLowerCase(),
+      kind: asset.kind,
+      name: asset.name,
+      payload: asset.payload,
+      refs: asset.refs,
+      artifacts: asset.artifacts,
+    }),
+    refs: asset.refs,
+  };
+}
+
+function outputSetDigest(outputs: readonly AssetPublicationOutput[]): string {
+  return digest(
+    outputs.map((output) => ({
+      guid: output.guid.toLowerCase(),
+      sourceKey: output.sourceKey,
+      kind: output.kind,
+      digest: output.digest,
+      refs: [...output.refs].map((guid) => guid.toLowerCase()),
+    })),
+  );
+}
+
+function publicationGeneration(
+  sourceRevision: string,
+  valueDigest: string,
+  outputs: string,
+): number {
+  const value = createHash('sha256')
+    .update(sourceRevision)
+    .update('\n')
+    .update(valueDigest)
+    .update('\n')
+    .update(outputs)
+    .digest('hex');
+  const generation = Number.parseInt(value.slice(0, 8), 16);
+  return generation > 0 ? generation : 1;
+}
+
+export function createRuntimePackPublication(
+  input: RuntimePackPublicationInput,
+): RuntimePackPublication {
+  const assets = normalizedAssets(input.pack);
+  const semantic = {
+    schemaVersion: '2.0.0' as const,
+    kind: 'internal-text-package' as const,
+    assets: [...assets].sort((left, right) =>
+      left.guid.toLowerCase().localeCompare(right.guid.toLowerCase()),
+    ),
+  };
+  const valueDigest = input.digest ?? digest(semantic);
+  const outputs = input.outputs ?? assets.map(outputFor);
+  const outputDigest = outputSetDigest(outputs);
+  const generation =
+    input.generation ?? publicationGeneration(input.sourceRevision, valueDigest, outputDigest);
+  const externalEvidence = input.externalEvidence ?? [];
+  const inputFingerprint = input.inputFingerprint ?? input.sourceRevision;
+  const publication: AssetPublicationEnvelope = {
+    schemaVersion: 'asset-publication/1',
+    sourcePath: input.sourcePath,
+    sourceRevision: input.sourceRevision,
+    generation,
+    digest: valueDigest,
+    outputSetDigest: outputDigest,
+    outputs,
+    receipt: {
+      schemaVersion: 'asset-publication-receipt/1',
+      sourcePath: input.sourcePath,
+      sourceRevision: input.sourceRevision,
+      inputFingerprint,
+      outputDigest: valueDigest,
+      outputSetDigest: outputDigest,
+      externalEvidence,
+    },
+    externalEvidence,
+    current: {
+      generation,
+      digest: valueDigest,
+      outputSetDigest: outputDigest,
+      packageUrl: input.packageUrl,
+      receiptKey: inputFingerprint,
+    },
+  };
+  return {
+    pack: {
+      ...semantic,
+      scopeId: input.scopeId,
+      generation,
+      digest: valueDigest,
+      outputSetDigest: outputDigest,
+    },
+    publication,
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,23 @@
+import type { PackV2, PackV2Error, Result } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+
+import { validatePackV2 } from './schema-compiled.js';
+
+export { validateMeta, validatePack, validatePackV2 } from './schema-compiled.js';
+
+/**
+ * Parse a Pack v2 envelope without loading the Node-only scanner/evidence
+ * barrel. Browser runtime consumers should import this subpath.
+ */
+export function parsePackV2(value: unknown): Result<PackV2, PackV2Error> {
+  if (!validatePackV2(value)) {
+    return err({
+      code: 'pack-v2-envelope-invalid',
+      expected: 'a Pack v2 envelope with unique asset GUIDs and valid descriptors',
+      hint: 'validate the pack against packages/pack/schema/pack.schema.json and re-cook it',
+      detail: { observed: 'invalid pack', expected: 'schemaVersion 2.0.0' },
+    });
+  }
+
+  return ok(value);
+}