aimeat 3.1.0 → 3.3.0

package/dist/src/services/datapackage/contract.d.ts

@@ -0,0 +1,198 @@
+/** The Frictionless field types this node reads and writes. Deliberately small: a type nobody can
+ *  serialise deterministically is a type that produces two different files from one table. */
+export type FieldType = 'string' | 'integer' | 'number' | 'boolean' | 'date' | 'datetime' | 'any';
+export interface SchemaField {
+    name: string;
+    type: FieldType;
+    /** Present when inference saw no value at all for the field — the publisher should look. */
+    description?: string;
+}
+export interface TableSchema {
+    fields: SchemaField[];
+    /** Field names that must be present and non-empty on every row. */
+    primaryKey?: string[];
+}
+/** One tabular resource as a producer hands it over: rows plus either a schema or a request to infer. */
+export interface ResourceInput {
+    name: string;
+    rows: Array<Record<string, unknown>>;
+    /** 'infer' proposes types from the rows; a TableSchema declares them. See INFERENCE IS A PROPOSAL. */
+    schema: 'infer' | TableSchema;
+    title?: string;
+    description?: string;
+}
+/** The AIMEAT extension block — one root key, so a Frictionless reader that knows nothing about this
+ *  node still parses the descriptor and simply carries an object it does not interpret. */
+export interface AimeatBlock {
+    packageId: string;
+    contentHash: string;
+    /** REQUIRED. What changed against the previous version and why. A version nobody explained is a
+     *  version a consumer cannot decide about. */
+    changes: string;
+    producer: {
+        kind: 'workflow' | 'extension' | 'agent' | 'app' | 'manual';
+        ref?: string;
+        schedule?: string;
+    };
+    producedBy: {
+        gaii: string;
+        run?: string;
+        at: string;
+    };
+    /** Whether the Table Schemas were declared by the producer or proposed by inference. A consumer
+     *  reading `inferred` knows the types are a guess nobody has confirmed yet. */
+    schemaSource: 'declared' | 'inferred' | 'mixed';
+    parameters?: Record<string, unknown>;
+    sources?: Array<{
+        url?: string;
+        title?: string;
+        retrievedAt?: string;
+        role?: string;
+    }>;
+    lineage?: string[];
+    transformations?: Array<{
+        by: string;
+        what: string;
+    }>;
+    legalBasis?: string;
+    consentStatus?: string;
+    retention?: string;
+    license?: string;
+    supersedes?: string;
+    retentionPolicy?: {
+        keep: number;
+        unit: 'versions' | 'months';
+    };
+    /**
+     * The addressable `aimeat.provenance/v1` record for THIS version, when one was minted — an agent
+     * publishing is model-touched output and TARGET-058 says that gets declared rather than inferred.
+     *
+     * Deliberately OUTSIDE the content hash (see contentHashOf's allowlist). A provenance id is a
+     * freshly minted UUID, so putting it in the identity would make two identical runs produce two
+     * versions and destroy the determinism the whole format leans on. It is a fact ABOUT the version.
+     */
+    aiProvenanceId?: string;
+}
+export interface DescriptorResource {
+    name: string;
+    path: string;
+    profile: 'tabular-data-resource';
+    format: 'csv';
+    mediatype: 'text/csv';
+    encoding: 'utf-8';
+    schema: TableSchema;
+    /** Rows in the resource, so a consumer can size a fetch before making it. */
+    rowCount: number;
+    bytes: number;
+    /** sha256 of the canonical bytes of THIS resource. */
+    hash: string;
+    title?: string;
+    description?: string;
+}
+export interface Descriptor {
+    name: string;
+    profile: 'tabular-data-package';
+    resources: DescriptorResource[];
+    title?: string;
+    description?: string;
+    licenses?: Array<{
+        name: string;
+        path?: string;
+    }>;
+    created: string;
+    aimeat: AimeatBlock;
+}
+/** What a producer hands to `publish`, on every road. */
+export interface PublishInput {
+    name: string;
+    changes: string;
+    resources: ResourceInput[];
+    title?: string;
+    description?: string;
+    producer?: Partial<AimeatBlock['producer']>;
+    parameters?: Record<string, unknown>;
+    provenance?: Pick<AimeatBlock, 'sources' | 'lineage' | 'transformations' | 'legalBasis' | 'consentStatus' | 'retention' | 'license' | 'supersedes'>;
+    retentionPolicy?: AimeatBlock['retentionPolicy'];
+    /** What the caller said about how this was made (TARGET-058). Threaded to provenanceForWrite. */
+    declaredProvenance?: unknown;
+    /** An existing provenance record the caller asks to attach instead of minting a new one. */
+    declaredProvenanceId?: string;
+}
+/** A package name is an address segment, so it is constrained like one. */
+export declare const PACKAGE_NAME_RE: RegExp;
+/** A resource name becomes a file name under data/. */
+export declare const RESOURCE_NAME_RE: RegExp;
+export declare function validateName(name: string): string | null;
+/** `datapkg/{name}` — everything about one package lives under this. */
+export declare const packageKeyRoot: (name: string) => string;
+/** The IMMUTABLE address of one version's descriptor. */
+export declare const descriptorKey: (name: string, contentHash: string) => string;
+/** The IMMUTABLE address of one version's resource bytes. Matches `resources[].path` relative to
+ *  the descriptor, which is what makes a plain Frictionless client resolve it unaided. */
+export declare const resourceKey: (name: string, contentHash: string, resource: string) => string;
+/** The relative path recorded IN the descriptor. */
+export declare const resourcePath: (resource: string) => string;
+/** The MUTABLE pointer for a consumer following the newest version. */
+export declare const latestKey: (name: string) => string;
+/** `sha256:abc…` → `abc…`. Every key uses the bare digest; every field carries the prefix. */
+export declare function bare(hash: string): string;
+/** The public, permanent, auth-free URL of a stored key under an owner. */
+export declare function publicUrl(baseUrl: string, ownerGhii: string, key: string): string;
+/** `pkg:{owner}/{name}` — the package's stable identity, independent of any one version. */
+export declare const packageId: (ownerName: string, name: string) => string;
+/**
+ * THE VERSION IS THE CONTENT HASH, and this is the one function that decides it.
+ *
+ * Computed over the descriptor serialised with object keys sorted (utils/stable-json.ts), so a round
+ * trip through Postgres `jsonb` — which normalises key order — cannot change a package's identity.
+ * Each resource's own bytes are already summarised by `resources[].hash`, so hashing the descriptor
+ * covers both the schema and the data: change one value in one row and the resource hash moves,
+ * which moves this one.
+ *
+ * WHAT IS DELIBERATELY OUTSIDE IT, and why each one:
+ *
+ * - `created` and `producedBy.at`. Two identical runs of a deterministic producer must agree, or
+ *   "same input, same output" is a claim the node itself breaks every time a clock fires.
+ *
+ * - THE WHOLE PRODUCER BLOCK — `producer` and `producedBy`. This one was learned the hard way: with
+ *   it inside, the same rows published by a schedule and by a workflow step hashed differently, so
+ *   they landed at two addresses and "the producer is interchangeable" was false. The E2E that
+ *   asserts a second producer reaches the SAME version is what caught it. WHO made a version is a
+ *   fact ABOUT the version, not part of what the version IS — the same table is the same table
+ *   whether a clock, a workflow, an agent or a person produced it.
+ *
+ *   The consequence is deliberate and is what makes the address immutable: a later identical run
+ *   finds the descriptor already stored, answers `unchanged`, and does NOT rewrite it. So the
+ *   producer recorded at an address is whoever produced it FIRST, and one address can never hold
+ *   two different byte sequences.
+ *
+ * - `supersedes`, for exactly the same reason one step further on. It names the version this one
+ *   REPLACED, which is a fact about where this version sits in a history rather than about what it
+ *   contains. With it inside the identity, republishing the same rows a second time would hash
+ *   differently purely because a previous version now existed, and the same table would land at two
+ *   addresses — the defect the producer block already taught us, wearing a different hat.
+ *
+ * What IS inside: the data, every Table Schema, the change description (a version is partly its
+ * explanation), the provenance block, and `schemaSource` — because "declared" and "inferred" are a
+ * real difference to whoever reads the types.
+ */
+export declare function contentHashOf(descriptor: Omit<Descriptor, 'aimeat'> & {
+    aimeat: Omit<AimeatBlock, 'contentHash'>;
+}): string;
+/** sha256 of one resource's canonical bytes. */
+export declare function bytesHash(data: Buffer): string;
+/** What `latest.json` holds — small on purpose, so following the newest version is one cheap GET. */
+export interface LatestPointer {
+    packageId: string;
+    name: string;
+    contentHash: string;
+    descriptorUrl: string;
+    updatedAt: string;
+    /** The last run that FAILED, if the newest attempt did. The package stays on the version below,
+     *  and this is how a consumer learns the difference between "unchanged" and "broken". */
+    lastError?: {
+        at: string;
+        message: string;
+    };
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/src/services/datapackage/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../../src/services/datapackage/contract.ts"],"names":[],"mappings":"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"}

package/dist/src/services/datapackage/contract.js

@@ -0,0 +1,140 @@
+/**
+ * @file src/services/datapackage/contract.ts
+ * @description THE AIMEAT Data Package contract: what a package is, where it lives, and what its
+ *   version is called. Everything else in this directory implements it, and the three bindings
+ *   (ctx.datapackage, the browser library, the MCP tools) are doors onto that one implementation.
+ *
+ *   WHY ONE IMPLEMENTATION AND NOT THREE. A package's identity is a content hash. Two pieces of code
+ *   that compute it differently produce two identities for the same bytes, and every consumer pinned
+ *   to a hash breaks silently. This node has already paid for that shape once — an app and its
+ *   extension hashed the same spreadsheet inputs differently, so every value the app computed looked
+ *   stale to the server forever (see EXT_HASH_REFERENCE_JS in services/extension-runtime.ts). So the
+ *   hash, the schema inference, the validation and the CSV serialisation live HERE, on the server,
+ *   and a browser app reaches them over `/v1/datapackages` rather than reimplementing them.
+ *
+ *   THE FORMAT is Frictionless Data Package: `datapackage.json` with a Table Schema per tabular
+ *   resource, extended under one `aimeat` root key. Nothing is stored twice — the ODPS descriptor,
+ *   the OData metadata and an XLSX header row are all projections of the Table Schema, so they
+ *   cannot drift from it.
+ *
+ *   THE ADDRESS is `datapkg/{name}/{contentHash}/datapackage.json`, with `resources[].path` a
+ *   sibling relative path (`data/rows.csv`) exactly as Frictionless expects, so `frictionless-py`,
+ *   R and the JS client resolve it with no AIMEAT knowledge at all. The hash IS in the path, which
+ *   is what makes a published version immutable for free: the same address can never answer with
+ *   different bytes. A separate, MUTABLE `datapkg/{name}/latest.json` is the pointer for a consumer
+ *   who follows the newest version rather than pinning one.
+ *
+ *   IT IS ALWAYS THE OWNER'S NAMESPACE. Not the agent's, not `scheduler@node`, not `ext/{name}/`.
+ *   A package produced from the app, on a clock, by a workflow step or by an agent has to land at
+ *   ONE permanent URL, or "the producer is interchangeable" is not true.
+ * @structure DataPackageInput/Descriptor/TableSchema/Field types · packageKeyRoot · descriptorKey ·
+ *   resourceKey · latestKey · publicUrl · contentHashOf · buildDescriptor
+ * @usage
+ *   import { buildDescriptor, contentHashOf, descriptorKey } from './contract.js';
+ * @version-history
+ *   v1.0.0 -- 2026-08-15 -- Initial (TARGET-063 vaihe 1, A4/B1/B2).
+ */
+import { createHash } from 'node:crypto';
+import { stableStringify } from '../../utils/stable-json.js';
+/** A package name is an address segment, so it is constrained like one. */
+export const PACKAGE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$/;
+/** A resource name becomes a file name under data/. */
+export const RESOURCE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$/;
+export function validateName(name) {
+    if (!PACKAGE_NAME_RE.test(name)) {
+        return `package name "${name}" must be lowercase letters, digits and dashes, 2-64 characters`;
+    }
+    return null;
+}
+/** `datapkg/{name}` — everything about one package lives under this. */
+export const packageKeyRoot = (name) => `datapkg/${name}`;
+/** The IMMUTABLE address of one version's descriptor. */
+export const descriptorKey = (name, contentHash) => `${packageKeyRoot(name)}/${bare(contentHash)}/datapackage.json`;
+/** The IMMUTABLE address of one version's resource bytes. Matches `resources[].path` relative to
+ *  the descriptor, which is what makes a plain Frictionless client resolve it unaided. */
+export const resourceKey = (name, contentHash, resource) => `${packageKeyRoot(name)}/${bare(contentHash)}/${resourcePath(resource)}`;
+/** The relative path recorded IN the descriptor. */
+export const resourcePath = (resource) => `data/${resource}.csv`;
+/** The MUTABLE pointer for a consumer following the newest version. */
+export const latestKey = (name) => `${packageKeyRoot(name)}/latest.json`;
+/** `sha256:abc…` → `abc…`. Every key uses the bare digest; every field carries the prefix. */
+export function bare(hash) {
+    return hash.replace(/^sha256:/, '');
+}
+/** The public, permanent, auth-free URL of a stored key under an owner. */
+export function publicUrl(baseUrl, ownerGhii, key) {
+    const path = key.split('/').map(encodeURIComponent).join('/');
+    return `${baseUrl.replace(/\/+$/, '')}/v1/pub/${encodeURIComponent(ownerGhii)}/${path}`;
+}
+/** `pkg:{owner}/{name}` — the package's stable identity, independent of any one version. */
+export const packageId = (ownerName, name) => `pkg:${ownerName}/${name}`;
+/**
+ * THE VERSION IS THE CONTENT HASH, and this is the one function that decides it.
+ *
+ * Computed over the descriptor serialised with object keys sorted (utils/stable-json.ts), so a round
+ * trip through Postgres `jsonb` — which normalises key order — cannot change a package's identity.
+ * Each resource's own bytes are already summarised by `resources[].hash`, so hashing the descriptor
+ * covers both the schema and the data: change one value in one row and the resource hash moves,
+ * which moves this one.
+ *
+ * WHAT IS DELIBERATELY OUTSIDE IT, and why each one:
+ *
+ * - `created` and `producedBy.at`. Two identical runs of a deterministic producer must agree, or
+ *   "same input, same output" is a claim the node itself breaks every time a clock fires.
+ *
+ * - THE WHOLE PRODUCER BLOCK — `producer` and `producedBy`. This one was learned the hard way: with
+ *   it inside, the same rows published by a schedule and by a workflow step hashed differently, so
+ *   they landed at two addresses and "the producer is interchangeable" was false. The E2E that
+ *   asserts a second producer reaches the SAME version is what caught it. WHO made a version is a
+ *   fact ABOUT the version, not part of what the version IS — the same table is the same table
+ *   whether a clock, a workflow, an agent or a person produced it.
+ *
+ *   The consequence is deliberate and is what makes the address immutable: a later identical run
+ *   finds the descriptor already stored, answers `unchanged`, and does NOT rewrite it. So the
+ *   producer recorded at an address is whoever produced it FIRST, and one address can never hold
+ *   two different byte sequences.
+ *
+ * - `supersedes`, for exactly the same reason one step further on. It names the version this one
+ *   REPLACED, which is a fact about where this version sits in a history rather than about what it
+ *   contains. With it inside the identity, republishing the same rows a second time would hash
+ *   differently purely because a previous version now existed, and the same table would land at two
+ *   addresses — the defect the producer block already taught us, wearing a different hat.
+ *
+ * What IS inside: the data, every Table Schema, the change description (a version is partly its
+ * explanation), the provenance block, and `schemaSource` — because "declared" and "inferred" are a
+ * real difference to whoever reads the types.
+ */
+export function contentHashOf(descriptor) {
+    // Rebuilt by naming what IS in the identity, rather than by removing what is not: a field added
+    // to AimeatBlock later must be considered on purpose, and an allowlist forces that. A denylist
+    // would quietly pull the next field in and move every existing version's hash.
+    const a = descriptor.aimeat;
+    const canonical = {
+        name: descriptor.name,
+        profile: descriptor.profile,
+        resources: descriptor.resources,
+        title: descriptor.title,
+        description: descriptor.description,
+        licenses: descriptor.licenses,
+        aimeat: {
+            packageId: a.packageId,
+            changes: a.changes,
+            schemaSource: a.schemaSource,
+            parameters: a.parameters,
+            sources: a.sources,
+            lineage: a.lineage,
+            transformations: a.transformations,
+            legalBasis: a.legalBasis,
+            consentStatus: a.consentStatus,
+            retention: a.retention,
+            license: a.license,
+            retentionPolicy: a.retentionPolicy,
+        },
+    };
+    return 'sha256:' + createHash('sha256').update(stableStringify(canonical)).digest('hex');
+}
+/** sha256 of one resource's canonical bytes. */
+export function bytesHash(data) {
+    return 'sha256:' + createHash('sha256').update(data).digest('hex');
+}
+//# sourceMappingURL=contract.js.map

package/dist/src/services/datapackage/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../../src/services/datapackage/contract.ts"],"names":[],"mappings":"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"}

package/dist/src/services/datapackage/ext-capability.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file src/services/datapackage/ext-capability.ts
+ * @description `ctx.datapackage` — the data-package contract as a HOST capability, because a
+ *   sandboxed extension cannot load a shared library and the deterministic producers live there.
+ *
+ *   WHY A HOST CAPABILITY AND NOT A LIBRARY. Extension actions run in QuickJS with no module
+ *   loader: the guest sees `ctx` and nothing else, and `ctx.fetch` answers with `text`, so even
+ *   pulling the library over HTTP and eval'ing it is not a road. That was the open question in the
+ *   spec, and this is the decided answer — the library's WORK (schema inference, validation, the
+ *   content hash, canonical CSV, the storage writes, the catalogue entry) happens on the host, and
+ *   the guest calls it. The browser binding and the MCP tools reach the SAME functions in
+ *   ./store.js, so a package built by an extension, an app and an agent is byte-identical.
+ *
+ *   PUBLISH THROWS WHEN THE GATE REFUSES. It does not return `{ ok: false }`, and that is not an
+ *   ergonomic preference: the scheduler and the workflow engine both record a normal return as a
+ *   successful run, so a producer whose data failed validation would show green having published
+ *   nothing. A throw is the only shape that reaches the owner on every road. `validate()` is the
+ *   separate, non-throwing call for a producer that wants to look before it leaps.
+ *
+ *   THE SIZE CEILING IS THE BRIDGE, not the file limit. Rows cross as one JSON string through
+ *   `vm.getString`, inside a sandbox whose memory ceiling is tens of megabytes, so the payload is
+ *   capped at the same 8 MB as `ctx.files` — one number for "what may cross in one call", refused
+ *   with a message naming the alternative rather than left to exhaust the VM.
+ * @structure makeExtensionDataPackage — the ctx.datapackage factory
+ * @usage
+ *   const datapackage = makeExtensionDataPackage({ storage, config, ownerGhii, producedBy });
+ *   const ctx = buildExtensionCtx({ …, datapackage });
+ * @version-history
+ *   v1.0.0 -- 2026-08-15 -- Initial (TARGET-063 vaihe 1, A4).
+ */
+import type { AimeatConfig } from '../../config.js';
+import type { Storage } from '../../storage/interface.js';
+import type { PublishInput, TableSchema } from './contract.js';
+import { type ValidationIssue } from './table.js';
+import { type ProducedBy } from './store.js';
+/** What may cross the sandbox bridge in one call, as serialised JSON. Same number as ctx.files. */
+export declare const MAX_DATAPACKAGE_PAYLOAD_BYTES: number;
+export interface ExtensionDataPackage {
+    publish(input: PublishInput): Promise<{
+        packageId: string;
+        contentHash: string;
+        descriptorUrl: string;
+        unchanged: boolean;
+        resources: Array<{
+            name: string;
+            url: string;
+            rowCount: number;
+            bytes: number;
+        }>;
+    }>;
+    validate(resources: Array<{
+        name: string;
+        rows: Array<Record<string, unknown>>;
+        schema: 'infer' | TableSchema;
+    }>): Promise<{
+        ok: boolean;
+        issues: ValidationIssue[];
+        schemas: Record<string, TableSchema>;
+    }>;
+    inferSchema(rows: Array<Record<string, unknown>>): Promise<TableSchema>;
+    open(ref: string): Promise<unknown | null>;
+    rows(ref: string, resource: string, opts?: {
+        offset?: number;
+        limit?: number;
+        select?: string[];
+    }): Promise<{
+        rows: Array<Record<string, unknown>>;
+        total: number;
+        schema: TableSchema;
+    } | null>;
+    fail(name: string, message: string): Promise<void>;
+}
+export declare function makeExtensionDataPackage(deps: {
+    config: AimeatConfig;
+    storage: Storage;
+    /**
+     * WHOSE package this is. Always the owner's GHII, on every road — never the agent GAII and never
+     * `scheduler@node`. A package produced from the app, on a clock, by a workflow step or by an
+     * agent must land at ONE permanent address, or the producer is not interchangeable.
+     */
+    ownerGhii: string;
+    /** Who actually produced it, for the provenance block. The exact principal, not the owner. */
+    producedBy: ProducedBy;
+}): ExtensionDataPackage;
+//# sourceMappingURL=ext-capability.d.ts.map

package/dist/src/services/datapackage/ext-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-capability.d.ts","sourceRoot":"","sources":["../../../../src/services/datapackage/ext-capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAwD,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEnG,mGAAmG;AACnG,eAAO,MAAM,6BAA6B,QAAkB,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACjC,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;QAClC,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAClF,SAAS,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACpF,CAAC,CAAC;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,GAAG,WAAW,CAAA;KAAE,CAAC,GAC5G,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,eAAe,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9F,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACxE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC7F,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACjG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAaD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,UAAU,EAAE,UAAU,CAAC;CAC1B,GAAG,oBAAoB,CA+DvB"}

package/dist/src/services/datapackage/ext-capability.js

@@ -0,0 +1,72 @@
+import { inferSchema, validateRows } from './table.js';
+import { openPackage, publishPackage, readRows, recordFailure } from './store.js';
+/** What may cross the sandbox bridge in one call, as serialised JSON. Same number as ctx.files. */
+export const MAX_DATAPACKAGE_PAYLOAD_BYTES = 8 * 1024 * 1024;
+/** Refuse an oversized payload at the boundary, naming what to do instead. */
+function guardSize(what, value) {
+    const bytes = Buffer.byteLength(JSON.stringify(value ?? null), 'utf8');
+    if (bytes > MAX_DATAPACKAGE_PAYLOAD_BYTES) {
+        throw new Error(`${what} is ${Math.round(bytes / 1024)} kB, over the ${MAX_DATAPACKAGE_PAYLOAD_BYTES / 1024 / 1024} MB sandbox `
+            + 'bridge limit. Publish the table in periods (one package version per window) rather than one '
+            + 'unbounded version, or produce it from a road with no sandbox between it and the data.');
+    }
+}
+export function makeExtensionDataPackage(deps) {
+    const { config, storage, ownerGhii, producedBy } = deps;
+    const store = { storage, config };
+    return {
+        async publish(input) {
+            guardSize('the package payload', input);
+            const out = await publishPackage(store, ownerGhii, input, producedBy);
+            if (!out.ok) {
+                // THROW, do not return a verdict. See the file header: an unattended road records a
+                // normal return as success, so a returned refusal is a green run that published
+                // nothing. The first coordinates travel in the message because a producer reading a
+                // log needs the row and the column, not a count.
+                const head = out.issues.slice(0, 5)
+                    .map(i => `${i.resource} row ${i.row}, ${i.field}: ${i.message}`)
+                    .join('; ');
+                throw new Error(`${out.code}: ${out.message}${head ? ` — ${head}` : ''}`);
+            }
+            return {
+                packageId: out.descriptor.aimeat.packageId,
+                contentHash: out.contentHash,
+                descriptorUrl: out.descriptorUrl,
+                unchanged: out.unchanged,
+                resources: out.resources,
+            };
+        },
+        async validate(resources) {
+            guardSize('the resources to validate', resources);
+            const issues = [];
+            const schemas = {};
+            for (const r of Array.isArray(resources) ? resources : []) {
+                const schema = r.schema === 'infer' ? inferSchema(r.rows ?? []) : r.schema;
+                schemas[r.name] = schema;
+                issues.push(...validateRows(r.name, r.rows ?? [], schema));
+            }
+            return { ok: issues.length === 0, issues, schemas };
+        },
+        async inferSchema(rows) {
+            guardSize('the rows to infer from', rows);
+            // A PROPOSAL. It is returned so the producer can look at it, adjust it and declare it;
+            // publishing with `schema: 'infer'` records `schemaSource: 'inferred'` in the descriptor
+            // so a consumer can see that nobody confirmed the types.
+            return inferSchema(Array.isArray(rows) ? rows : []);
+        },
+        async open(ref) {
+            const opened = await openPackage(store, String(ref || ''), config.nodeId);
+            return opened ? { ...opened.descriptor, descriptorUrl: opened.descriptorUrl } : null;
+        },
+        async rows(ref, resource, opts) {
+            return readRows(store, String(ref || ''), config.nodeId, String(resource || ''), opts ?? {});
+        },
+        async fail(name, message) {
+            // The producer saying so itself, for the case it can detect and the road cannot: an
+            // upstream that answered with an empty body, a source that returned yesterday's file.
+            // The run should ALSO throw; this is what leaves the reason on the package.
+            await recordFailure(store, ownerGhii, String(name || ''), String(message || 'the run failed'));
+        },
+    };
+}
+//# sourceMappingURL=ext-capability.js.map

package/dist/src/services/datapackage/ext-capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-capability.js","sourceRoot":"","sources":["../../../../src/services/datapackage/ext-capability.ts"],"names":[],"mappings":"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"}

package/dist/src/services/datapackage/odata.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @file src/services/datapackage/odata.ts
+ * @description The OData v4 projection of a data package: CSDL metadata from the Table Schema, and
+ *   the readable subset of the query language applied to rows. Pure — no HTTP, no storage.
+ *
+ *   WHY OData AT ALL, when the CSV already sits at a permanent address. Excel, Power BI and Tableau
+ *   have a native "OData feed" connector: a person pastes one URL and the workbook REFRESHES ITSELF
+ *   afterwards. A CSV link is a download, and a download is a copy that starts going stale the moment
+ *   it lands. This is the difference between a dataset somebody uses once and one they keep.
+ *
+ *   AN UNSUPPORTED QUERY OPTION IS AN ERROR, NEVER AN IGNORED ONE. This is the rule the whole file
+ *   is shaped around. If a client sends `$filter=weird(x)` and the server ignores it, the client
+ *   receives MORE ROWS THAN IT ASKED FOR and treats them as the answer — a silent wrong result that
+ *   looks exactly like a right one. So anything this implementation does not understand answers 501
+ *   naming what it does understand. A visibly missing feature is cheap; a filter that quietly did
+ *   nothing is a wrong number in somebody's report.
+ *
+ *   ONE SCHEMA, MANY PROJECTIONS. The Table Schema in the descriptor is the only place columns and
+ *   types are declared. The CSDL here, the CSV header, the ODPS product sheet and an agent's view of
+ *   the package are all derived from it, so none of them can drift from the data.
+ * @structure toCsdl · parseQuery · applyQuery · ODATA_SUPPORTED
+ * @usage
+ *   const xml = toCsdl(descriptor, 'https://…/v1/odata/alice/pkg');
+ *   const q = parseQuery(searchParams, resource.schema);
+ *   if (!q.ok) return 501;
+ *   const page = applyQuery(rows, q.value);
+ * @version-history
+ *   v1.0.0 -- 2026-08-15 -- Initial (TARGET-063 vaihe 1, the OData surface).
+ */
+import type { Descriptor, TableSchema } from './contract.js';
+/** Every system query option this implementation honours. Anything else is refused by name. */
+export declare const ODATA_SUPPORTED: readonly ["$select", "$top", "$skip", "$filter", "$orderby", "$count", "$format"];
+/** The synthetic key. A CSV row has no identity of its own, and OData requires an entity key — so
+ *  one is supplied rather than a natural column being promoted to a role it cannot fill. It is the
+ *  row's ordinal WITHIN THIS IMMUTABLE VERSION, which is stable precisely because the version is. */
+export declare const ROW_KEY = "RowId";
+/** A CSDL identifier: letters, digits and underscore, not starting with a digit. A column called
+ *  `first name` or `2026` is legal in a CSV and illegal here, so it is mapped rather than rejected —
+ *  and the mapping is recorded in the descriptor's own field name, which does not change. */
+export declare function edmName(raw: string): string;
+/**
+ * The CSDL v4 document (`$metadata`) for one package version.
+ *
+ * `Nullable="true"` on every property except the key, deliberately: a Table Schema's `primaryKey` is
+ * the only statement anybody made about required-ness, and claiming a column is non-nullable because
+ * it happened to be full in this version would be a promise the next version breaks.
+ */
+export declare function toCsdl(descriptor: Descriptor, namespace: string): string;
+export interface FilterNode {
+    field: string;
+    op: 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' | 'contains' | 'startswith' | 'endswith';
+    value: string | number | boolean | null;
+}
+export interface ParsedQuery {
+    select?: string[];
+    top?: number;
+    skip: number;
+    /** ANDed together. `or` is not supported, and saying so is the point — see the file header. */
+    filters: FilterNode[];
+    orderby: Array<{
+        field: string;
+        desc: boolean;
+    }>;
+    count: boolean;
+}
+export type ParseResult = {
+    ok: true;
+    value: ParsedQuery;
+} | {
+    ok: false;
+    code: 'NOT_IMPLEMENTED' | 'BAD_REQUEST';
+    message: string;
+};
+/**
+ * Read the system query options, refusing everything not understood.
+ *
+ * The `edmName` mapping runs in both directions here: a client saw `first_name` in the metadata and
+ * sends `$filter=first_name eq 'x'`, while the row still holds `first name`. Resolving through the
+ * schema means the client only ever has to know the names the metadata gave it.
+ */
+export declare function parseQuery(params: URLSearchParams, schema: TableSchema): ParseResult;
+export interface QueryPage {
+    rows: Array<Record<string, unknown>>;
+    /** Rows matching the filter, BEFORE $top/$skip — what `$count=true` reports. */
+    matched: number;
+}
+/**
+ * Apply the parsed query. `RowId` is assigned before filtering, so a row keeps the same key whatever
+ * a client asks for — a key that shifted with the query would make the entity identity meaningless.
+ */
+export declare function applyQuery(rows: Array<Record<string, unknown>>, q: ParsedQuery, schema: TableSchema): QueryPage;
+//# sourceMappingURL=odata.d.ts.map

package/dist/src/services/datapackage/odata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odata.d.ts","sourceRoot":"","sources":["../../../../src/services/datapackage/odata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAiC,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5F,+FAA+F;AAC/F,eAAO,MAAM,eAAe,mFAAoF,CAAC;AAajH;;qGAEqG;AACrG,eAAO,MAAM,OAAO,UAAU,CAAC;AAQ/B;;6FAE6F;AAC7F,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG3C;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAqBxE;AAeD,MAAM,WAAW,UAAU;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC;IACrF,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,WAAW;IACxB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACjD,KAAK,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,WAAW,GACjB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAiB9E;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,GAAG,WAAW,CAsFpF;AAmDD,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrC,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,CAqB/G"}