@tangle-network/agent-interface 0.36.0 → 0.37.0

package/dist/agent-improvement-source.js

@@ -1,26 +1,140 @@
+import parseSpdxExpression from "spdx-expression-parse";
 import { z } from "zod";
-import { sha256DigestSchema } from "./agent-candidate-schema-common.js";
+import { isWellFormedUnicode, looksLikeCredential, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 /** Metadata key that binds a measured improvement to its exact external source. */
 export const AGENT_IMPROVEMENT_SOURCE_METADATA_KEY = "agentImprovementSource";
+function publicSourceTextSchema(maxLength, label) {
+    return z
+        .string()
+        .max(maxLength)
+        .refine(isWellFormedUnicode, `${label} must be well-formed Unicode`)
+        .refine((value) => !looksLikeCredential(value), `${label} cannot carry credentials`);
+}
+const sourceIdentitySchema = publicSourceTextSchema(256, "source identity")
+    .transform((value) => value.trim())
+    .pipe(z.string().min(1, "source identity cannot be blank"));
+const sourceRevisionSchema = z.union([
+    publicSourceTextSchema(256, "source revision")
+        .transform((value) => value.trim())
+        .pipe(z.string().min(1, "source revision cannot be blank")),
+    z.number().int().nonnegative(),
+]);
+const sourceStatementSchema = publicSourceTextSchema(16_384, "source statement").refine((value) => value.trim().length > 0, "statement cannot be blank");
+const sourceStatementListSchema = z
+    .array(sourceStatementSchema)
+    .min(1)
+    .max(128)
+    .refine((values) => new Set(values).size === values.length, "statements must be unique");
+function containsCustomLicenseReference(expression) {
+    if ("license" in expression) {
+        return (expression.license.startsWith("LicenseRef-") ||
+            expression.license.includes(":LicenseRef-"));
+    }
+    return (containsCustomLicenseReference(expression.left) ||
+        containsCustomLicenseReference(expression.right));
+}
+/** License terms retained with an imported source. */
+export const agentSourceLicenseSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("spdx"),
+        expression: z
+            .string()
+            .trim()
+            .min(1)
+            .max(1_024)
+            .refine((expression) => {
+            try {
+                return !containsCustomLicenseReference(parseSpdxExpression(expression));
+            }
+            catch {
+                return false;
+            }
+        }, "license expression must use standard SPDX identifiers; content-pin custom terms with kind=custom"),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("custom"),
+        name: sourceIdentitySchema,
+        /** URL or repository-relative path from which the exact terms can be recovered. */
+        reference: publicSourceTextSchema(2_048, "license reference")
+            .transform((value) => value.trim())
+            .pipe(z.string().min(1, "license reference cannot be blank")),
+        /** Digest of the custom license text, not of its URL or file name. */
+        termsDigest: sha256DigestSchema,
+    })
+        .strict(),
+]);
+/**
+ * One content transition applied while importing a source.
+ *
+ * `identity` and `revision` pin the transformer. Input/output digests make the
+ * ordered chain auditable without embedding executable transformation code.
+ * `procedureDigest` pins the implementation and non-secret configuration used
+ * for that step.
+ */
+export const agentSourceTransformationSchema = z
+    .object({
+    kind: z.enum(["normalization", "transformation"]),
+    identity: sourceIdentitySchema,
+    revision: sourceRevisionSchema,
+    procedureDigest: sha256DigestSchema,
+    inputDigest: sha256DigestSchema,
+    outputDigest: sha256DigestSchema,
+})
+    .strict();
 /**
  * Stable reference for the state from which an improvement candidate was made.
  * `sourceIdentity` identifies the provider object; `sourceDigest` is the exact
- * measured source state; `sourceRevision` is an
+ * measured source state consumed by the candidate; `sourceRevision` is an
  * opaque provider version retained to make stale-source errors intelligible to
  * callers. A revision may be numeric or textual because providers use both
  * counters and immutable revision identifiers.
+ *
+ * Optional license, attribution, and notice fields preserve obligations when a
+ * public source becomes an improvement input. When transformations are
+ * present, their first input pins the fetched source bytes, every adjacent
+ * digest must join, and the final output must equal `sourceDigest`.
  */
 export const agentImprovementSourceSchema = z
     .object({
     kind: z.string().trim().min(1).max(100).regex(/^[a-z][a-z0-9-]*$/),
-    sourceIdentity: z.string().trim().min(1).max(256),
+    sourceIdentity: sourceIdentitySchema,
     sourceDigest: sha256DigestSchema,
-    sourceRevision: z.union([
-        z.string().trim().min(1).max(256),
-        z.number().int().nonnegative(),
-    ]),
+    sourceRevision: sourceRevisionSchema,
+    license: agentSourceLicenseSchema.optional(),
+    attribution: sourceStatementListSchema.optional(),
+    notices: sourceStatementListSchema.optional(),
+    transformations: z
+        .array(agentSourceTransformationSchema)
+        .min(1)
+        .max(128)
+        .optional(),
 })
-    .strict();
+    .strict()
+    .superRefine((source, ctx) => {
+    const transformations = source.transformations;
+    if (transformations === undefined)
+        return;
+    for (let index = 1; index < transformations.length; index++) {
+        if (transformations[index]?.inputDigest !==
+            transformations[index - 1]?.outputDigest) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["transformations", index, "inputDigest"],
+                message: "transformation input must equal the previous output",
+            });
+        }
+    }
+    if (transformations.at(-1)?.outputDigest !== source.sourceDigest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["sourceDigest"],
+            message: "source digest must equal the final transformation output",
+        });
+    }
+});
 /** Attach one validated source reference to signed improvement metadata. */
 export function agentImprovementSourceMetadata(source) {
     return {

package/dist/agent-profile-improvement-schema.d.ts

@@ -195,9 +195,31 @@ export declare const agentProfileImprovementExperimentSchema: z.ZodObject<{
     digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
     source: z.ZodObject<{
         kind: z.ZodString;
-        sourceIdentity: z.ZodString;
+        sourceIdentity: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
         sourceDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
-        sourceRevision: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        sourceRevision: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>, z.ZodNumber]>;
+        license: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"spdx">;
+            expression: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"custom">;
+            name: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+            reference: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+            termsDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>], "kind">>;
+        attribution: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        notices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        transformations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                normalization: "normalization";
+                transformation: "transformation";
+            }>;
+            identity: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+            revision: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>, z.ZodNumber]>;
+            procedureDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            inputDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            outputDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>;
     executionRef: z.ZodObject<{
         identity: z.ZodString;
@@ -702,9 +724,31 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
         digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
         source: z.ZodObject<{
             kind: z.ZodString;
-            sourceIdentity: z.ZodString;
+            sourceIdentity: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
             sourceDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
-            sourceRevision: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            sourceRevision: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>, z.ZodNumber]>;
+            license: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"spdx">;
+                expression: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"custom">;
+                name: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+                reference: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+                termsDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>], "kind">>;
+            attribution: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            notices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            transformations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    normalization: "normalization";
+                    transformation: "transformation";
+                }>;
+                identity: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+                revision: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>, z.ZodNumber]>;
+                procedureDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                inputDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                outputDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>>>;
         }, z.core.$strict>;
         executionRef: z.ZodObject<{
             identity: z.ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -34,10 +34,12 @@
   ],
   "dependencies": {
     "@noble/hashes": "1.8.0",
+    "spdx-expression-parse": "5.0.0",
     "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "25.6.0",
+    "@types/spdx-expression-parse": "4.0.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },