aimeat 3.2.0 → 3.3.0

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

@@ -0,0 +1,183 @@
+/**
+ * @file src/services/datapackage/odps.ts
+ * @description The product sheet, as a projection of the descriptor. `odps.yaml` is generated into
+ *   every published version so a package is describable to a buyer without anyone authoring a second
+ *   document about it.
+ *
+ *   ONE SCHEMA, MANY PROJECTIONS, and this is one of the projections. The Table Schema is the only
+ *   place columns and types are declared; the ODPS sheet, the CSV header and an agent's view of the
+ *   package are all derived from it, so they cannot drift. Nothing here is authored — every field
+ *   traces to something the descriptor already holds, which is why it stays true when the package
+ *   changes and why it needs no mapping layer to maintain.
+ *
+ *   THREE PLACES THE SPEC'S CLOSED ENUMS DO NOT FIT, handled the same way each time: state it under
+ *   `x-aimeat` rather than bend a field to nearly mean it.
+ *   - `dataAccess[].format` is `TOON|JSON|XML|CSV|Excel|zip|plain text|GraphQL|MCP`. CSV is on it, so
+ *     today's canonical form declares itself honestly. Parquet is not, and when Parquet arrives it
+ *     goes in the extension block rather than being called `zip`.
+ *   - `specification` is `OAS|RAML|Slate|MCP`. A plain file has no API specification, so the field is
+ *     simply absent rather than filled with the closest wrong answer.
+ *   - `updateFrequency` IS in the SLA dimension enum, and it is filled from the producer's cron —
+ *     recorded, not described. A package nobody schedules gets no SLA block at all: an unstated
+ *     service level is an absent one, never a promise of daily.
+ * @structure descriptorToOdps · odpsYamlKey
+ * @usage const doc = descriptorToOdps({ descriptor, ownerGhii, baseUrl, resourceUrls });
+ * @version-history
+ *   v1.0.0 -- 2026-08-15 -- Initial (TARGET-063 vaihe 1: "the package is sellable").
+ */
+import { stringify as yamlStringify } from 'yaml';
+import { ODPS_VERSION, ODPS_SCHEMA_URL_YAML } from '../exchange-odps.js';
+import { bare, packageKeyRoot } from './contract.js';
+/** Where the generated sheet sits, beside the descriptor it was projected from. */
+export const odpsYamlKey = (name, contentHash) => `${packageKeyRoot(name)}/${bare(contentHash)}/odps.yaml`;
+/**
+ * A cron expression as an ODPS `updateFrequency` objective.
+ *
+ * Deliberately coarse: the SLA dimension takes a number and a unit, and a cron says more than that
+ * shape can hold. What a buyer needs from it is the ORDER OF MAGNITUDE — is this refreshed daily or
+ * quarterly — and an expression it cannot express is answered with null rather than a rounded
+ * fiction. `unit: 'never'` is the enum's own word for "no cadence", which is not the same as a
+ * cadence nobody stated.
+ */
+function updateFrequencyFrom(cron) {
+    if (!cron)
+        return null;
+    const parts = cron.trim().split(/\s+/);
+    if (parts.length < 5)
+        return null;
+    const [, , dom, month, dow] = parts;
+    if (month !== '*')
+        return { objective: 1, unit: 'months' };
+    if (dom !== '*')
+        return { objective: 1, unit: 'months' };
+    if (dow !== '*') {
+        // A single weekday is weekly; a list of them is more often than that, and "days" is the
+        // honest floor rather than a fraction of a week.
+        return /^[0-7]$/.test(dow) ? { objective: 1, unit: 'weeks' } : { objective: 1, unit: 'days' };
+    }
+    return { objective: 1, unit: 'days' };
+}
+/**
+ * Project one published version into an ODPS v4.1 document.
+ *
+ * Everything traces to the descriptor. `status` is 'production' because a published version at a
+ * permanent immutable address is exactly that — a draft is a thing that has not been published, and
+ * this function only ever sees published ones.
+ */
+export function descriptorToOdps(input) {
+    const { descriptor: d, resourceUrls, descriptorUrl } = input;
+    const lang = input.lang ?? 'en';
+    const a = d.aimeat;
+    const columns = d.resources.flatMap(r => r.schema.fields.map(f => `${r.name}.${f.name} (${f.type})`));
+    const rowTotal = d.resources.reduce((n, r) => n + r.rowCount, 0);
+    const details = {
+        name: d.title ?? d.name,
+        productID: a.packageId,
+        // v4.1 `type`: this is a dataset delivered as files, which is what 'dataset' means here.
+        type: 'dataset',
+        status: 'production',
+        visibility: 'public',
+        version: bare(a.contentHash).slice(0, 12),
+        description: d.description
+            ?? `${rowTotal} rows across ${d.resources.length} resource(s), as a Frictionless Data Package.`,
+        // The change note is the version's own explanation, and ODPS has a field that means exactly
+        // that. It is required on every AIMEAT version, so this is never empty.
+        versionNotes: a.changes,
+        // The columns, from the ONE place they are declared. A buyer reading the sheet knows the
+        // shape before contracting, and this line cannot drift from the data.
+        tags: ['frictionless', 'data-package', d.name],
+        outputFileFormats: ['CSV'],
+        ...(a.sources?.length ? {
+            recommendedDataProducts: a.sources.filter(s => s.url).map(s => s.url),
+        } : {}),
+        // A free sample without a separate artefact: the first resource IS the file, and it is
+        // world-readable. Nobody buys data blind, and here they do not have to.
+        ...(Object.values(resourceUrls)[0] ? { contentSample: Object.values(resourceUrls)[0] } : {}),
+    };
+    const dataAccess = {
+        default: {
+            name: { [lang]: 'Permanent file address' },
+            description: {
+                [lang]: 'The resource CSV at a permanent, immutable URL. No authentication, no API key, '
+                    + 'byte ranges supported. The version is the content hash in the path, so this address '
+                    + 'can never answer with different bytes.',
+            },
+            outputPortType: 'file',
+            format: 'CSV',
+            authenticationMethod: 'none',
+            accessURL: Object.values(resourceUrls)[0] ?? descriptorUrl,
+            documentationURL: descriptorUrl,
+            hashType: 'SHA-256',
+            checksum: bare(d.resources[0]?.hash ?? a.contentHash),
+        },
+        descriptor: {
+            name: { [lang]: 'Frictionless descriptor' },
+            description: {
+                [lang]: 'datapackage.json with a Table Schema per resource. frictionless-py, R and the JS '
+                    + 'client resolve the resources from it with no AIMEAT knowledge.',
+            },
+            outputPortType: 'file',
+            format: 'JSON',
+            authenticationMethod: 'none',
+            accessURL: descriptorUrl,
+            documentationURL: descriptorUrl,
+        },
+    };
+    const freq = updateFrequencyFrom(a.producer.schedule);
+    const sla = freq
+        ? {
+            declarative: [{
+                    name: { [lang]: 'Producer cadence' },
+                    description: {
+                        [lang]: `Refreshed by a ${a.producer.kind} producer on the schedule "${a.producer.schedule}". `
+                            + 'A run that fails writes no version: the package stays on its previous one and the '
+                            + 'failure is recorded on the package pointer.',
+                    },
+                    dimensions: [{
+                            dimension: 'updateFrequency',
+                            objective: String(freq.objective),
+                            unit: freq.unit,
+                        }],
+                }],
+        }
+        : null;
+    return {
+        schema: ODPS_SCHEMA_URL_YAML,
+        version: ODPS_VERSION,
+        product: {
+            details: { [lang]: details },
+            dataAccess,
+            ...(a.license ? { license: { scope: { definition: a.license } } } : {}),
+            ...(sla ? { SLA: sla } : {}),
+            // Everything the closed enums cannot hold, stated rather than bent into a near-fit.
+            'x-aimeat': {
+                packageId: a.packageId,
+                contentHash: a.contentHash,
+                descriptorUrl,
+                profile: 'aimeat.datapackage/v1',
+                schemaSource: a.schemaSource,
+                producer: a.producer,
+                producedBy: a.producedBy,
+                resources: d.resources.map(r => ({
+                    name: r.name, rowCount: r.rowCount, bytes: r.bytes, hash: r.hash,
+                    url: resourceUrls[r.name] ?? null,
+                    fields: r.schema.fields.map(f => ({ name: f.name, type: f.type })),
+                })),
+                columns,
+                ...(a.legalBasis ? { legalBasis: a.legalBasis } : {}),
+                ...(a.consentStatus ? { consentStatus: a.consentStatus } : {}),
+                ...(a.retention ? { retention: a.retention } : {}),
+                ...(a.retentionPolicy ? { retentionPolicy: a.retentionPolicy } : {}),
+                ...(a.lineage?.length ? { lineage: a.lineage } : {}),
+                ...(a.transformations?.length ? { transformations: a.transformations } : {}),
+                ...(a.supersedes ? { supersedes: a.supersedes } : {}),
+                ...(a.aiProvenanceId ? { aiProvenanceId: a.aiProvenanceId } : {}),
+            },
+        },
+    };
+}
+/** The generated sheet as YAML — the format ODPS leads with. */
+export function odpsToYamlDocument(doc) {
+    return yamlStringify(doc, { lineWidth: 0 });
+}
+//# sourceMappingURL=odps.js.map

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

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

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

@@ -0,0 +1,143 @@
+/**
+ * @file src/services/datapackage/store.ts
+ * @description Publishing and reading an AIMEAT Data Package — the one implementation the three
+ *   bindings (ctx.datapackage, the browser library, the MCP tools) all reach.
+ *
+ *   REFUSE BEFORE YOU WRITE. `publish` validates every resource against its own Table Schema and
+ *   returns the coordinates of what is wrong WITHOUT having stored a byte. The order is the point:
+ *   this node's own audit found three defects of exactly one shape — bytes written before the name
+ *   was claimed, a paywall standing down before comparing the coordinate, a response sent before the
+ *   work it announced. A publish that wrote the CSV and then discovered the schema was violated would
+ *   leave a half-version at a permanent address, which is worse than no version at all.
+ *
+ *   AND A FAILED RUN LEAVES THE PREVIOUS VERSION STANDING. `recordFailure` writes the reason onto
+ *   the mutable `latest.json` pointer and touches nothing else, so a consumer following the newest
+ *   version keeps reading the last good one and can see that the newest attempt failed, when, and
+ *   why. No empty version, no truncated version, no silent success.
+ *
+ *   TWO SURFACES, ONE TRUTH. The BYTES in storage are canonical — a permanent, auth-free,
+ *   range-readable address that DuckDB, pandas and frictionless-py read with no AIMEAT knowledge.
+ *   The knowledge package written beside them is a CATALOGUE entry (`content_type: 'dataset'`, the
+ *   value the closed union already has — `data-package` is not in it) so the package appears where a
+ *   person and an agent look for knowledge. The catalogue points at the bytes; it never holds them,
+ *   because a knowledge package is a collection of memory entries and memory does not carry files.
+ * @structure publishPackage · openPackage · readRows · recordFailure · listPackages
+ * @usage
+ *   const out = await publishPackage({ storage, config }, ownerGhii, input, producedBy);
+ *   if (!out.ok) return out.issues;
+ * @version-history
+ *   v1.0.0 -- 2026-08-15 -- Initial (TARGET-063 vaihe 1, A4/B1/B2).
+ */
+import type { AimeatConfig } from '../../config.js';
+import type { Storage } from '../../storage/interface.js';
+import { type Descriptor, type LatestPointer, type PublishInput, type TableSchema } from './contract.js';
+import { type ValidationIssue } from './table.js';
+export interface StoreDeps {
+    storage: Storage;
+    config: AimeatConfig;
+}
+/** Who produced this version. Every road knows it; none of them may make it up. */
+export interface ProducedBy {
+    /** The exact principal: an owner GHII, an agent GAII, or the owner on an unattended road. */
+    gaii: string;
+    kind: Descriptor['aimeat']['producer']['kind'];
+    ref?: string;
+    schedule?: string;
+    run?: string;
+}
+export type PublishResult = {
+    ok: true;
+    descriptor: Descriptor;
+    contentHash: string;
+    descriptorUrl: string;
+    unchanged: boolean;
+    resources: Array<{
+        name: string;
+        url: string;
+        rowCount: number;
+        bytes: number;
+    }>;
+    /** Versions the owner's retention policy removed on this publish. Empty when no policy is
+     *  set, which is the default: keep everything. Returned so the answer can SAY what was
+     *  deleted — a deletion nobody can see is how a history disappears unnoticed. */
+    pruned: string[];
+} | {
+    ok: false;
+    code: 'INVALID_INPUT' | 'QUALITY_GATE';
+    message: string;
+    issues: ValidationIssue[];
+};
+/**
+ * Build, check and store one version.
+ *
+ * `unchanged: true` means the content hash matched what is already published: the same address
+ * already holds these exact bytes, so nothing was rewritten. That is not a failure and not a new
+ * version — it is a deterministic producer proving it is deterministic, and the caller should say
+ * so rather than announcing an update that did not happen.
+ */
+export declare function publishPackage(deps: StoreDeps, ownerGhii: string, input: PublishInput, producedBy: ProducedBy): Promise<PublishResult>;
+/**
+ * A run failed. The package stays on the version it had; the pointer says the newest attempt did not
+ * land, when, and why. This is the whole of "epäonnistuminen näkyy, eikä sitä peitetä": no empty
+ * version is written, and a consumer polling `latest.json` learns the difference between a package
+ * that has not changed and one whose producer is broken.
+ */
+export declare function recordFailure(deps: StoreDeps, ownerGhii: string, name: string, message: string): Promise<void>;
+export interface OpenedPackage {
+    descriptor: Descriptor;
+    descriptorUrl: string;
+    latest?: LatestPointer;
+}
+/**
+ * Read a package back. `ref` is `pkg:{owner}/{name}` for the newest version, or
+ * `pkg:{owner}/{name}@sha256:…` to pin one. A pinned reference always answers with the same bytes,
+ * which is what makes pinning worth anything.
+ */
+export declare function openPackage(deps: StoreDeps, ref: string, nodeId: string): Promise<OpenedPackage | null>;
+/** Rows of one resource, paginated. The caller names the window; nothing here decides to send a
+ *  whole table into somebody's context because it happened to fit. */
+export declare function readRows(deps: StoreDeps, ref: string, nodeId: string, resource: string, opts?: {
+    offset?: number;
+    limit?: number;
+    select?: string[];
+}): Promise<{
+    rows: Array<Record<string, unknown>>;
+    total: number;
+    schema: TableSchema;
+} | null>;
+/** Every package one owner has, newest version each, with any recorded failure. */
+export declare function listPackages(deps: StoreDeps, ownerGhii: string): Promise<LatestPointer[]>;
+/** One entry in a package's history: enough to decide about a version without opening it. */
+export interface VersionEntry {
+    contentHash: string;
+    /** When this version's descriptor was written. Not the descriptor's own `created`, which is the
+     *  first producer's clock; this is when these bytes landed here. */
+    at: string;
+    /** True for the one `latest.json` points at. There is exactly one, unless nothing is published. */
+    current: boolean;
+    /** The mandatory explanation. It is the reason a history is readable rather than a list of hashes. */
+    changes: string;
+    rowCount: number;
+    bytes: number;
+    descriptorUrl: string;
+    supersedes?: string;
+}
+/**
+ * Every version of one package, newest first.
+ *
+ * The versions are DISCOVERED FROM THE KEYS rather than from an index, because the keys are the
+ * index: a version is a directory named by its content hash, so nothing can be published without
+ * appearing here and nothing can be listed here without existing. An index would be a second thing
+ * to keep in step with the first.
+ *
+ * Each descriptor is read, which is one small GET per version. That is what makes `changes` and
+ * `rowCount` available, and it is bounded by the owner's retention policy rather than by time.
+ */
+export declare function listVersions(deps: StoreDeps, ownerGhii: string, name: string): Promise<VersionEntry[]>;
+/** `pkg:{owner}/{name}` or `pkg:{owner}/{name}@sha256:…`, or the bare `{name}` of your own. */
+export declare function parseRef(ref: string, nodeId: string): {
+    ownerGhii: string;
+    name: string;
+    contentHash?: string;
+} | null;
+//# sourceMappingURL=store.d.ts.map

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

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