agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/dist/registries/artifactRegistry.js

@@ -6,6 +6,7 @@ import { resolveProfileDirOverride } from "../core/envPaths.js";
 import { resolvePath } from "../core/paths.js";
 import { resolveSourceRoot } from "../core/sourceRoot.js";
 import { resolveCandidate } from "../state/installRoot.js";
+import { ARTIFACT_PROTOCOL_PATHS } from "./artifactProtocolIds.js";
 function sourceRoot() {
     return resolveSourceRoot();
 }
@@ -37,12 +38,11 @@ export function normalizePath(p) {
     s = s.replace(/<objective-name>/g, "<name>");
     return s.trim();
 }
-const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
 const URI_SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:/;
 const ENCODED_TRAVERSAL_RE = /%(?:2e|2f|5c)/i;
 const WINDOWS_DRIVE_RE = /^[A-Za-z]:[\\/]/;
 function rejectUnsafeArtifactPath(p, artifactId) {
-    if (CONTROL_CHAR_RE.test(p)) {
+    if ([...p].some((char) => char.charCodeAt(0) <= 31 || char.charCodeAt(0) === 127)) {
         throw new Error(`artifact '${artifactId}' path contains control characters`);
     }
     if (ENCODED_TRAVERSAL_RE.test(p)) {
@@ -69,34 +69,140 @@ function projectPath(projectRoot, artifactPath, artifactId) {
     return resolved;
 }
 export const EXPECTED_ARTIFACT_SCHEMA_VERSION = "1.0.0";
-function schemaMetas(dir) {
-    const metas = new Map();
+function readSchemaMeta(file) {
+    const meta = loadYaml(file).meta;
+    if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+        return null;
+    }
+    return meta;
+}
+function warnMalformedSchemaMeta(name) {
+    process.stderr.write(`warning: artifact schema ${name} is missing meta; expected v3 schema version ${EXPECTED_ARTIFACT_SCHEMA_VERSION}\n`);
+}
+function warnSchemaVersionMismatch(meta, name) {
+    const version = String(meta.version ?? "").trim();
+    if (!version || version !== EXPECTED_ARTIFACT_SCHEMA_VERSION) {
+        const reported = version || "(missing)";
+        process.stderr.write(`warning: artifact schema ${name} version ${reported} does not match expected v3 schema version ${EXPECTED_ARTIFACT_SCHEMA_VERSION}\n`);
+    }
+}
+function listSchemaFiles(dir) {
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
-        return metas;
+        return [];
     }
-    const files = fs
+    return fs
         .readdirSync(dir)
         .filter((name) => name.endsWith(".yaml"))
         .sort();
-    for (const name of files) {
-        const meta = loadYaml(path.join(dir, name)).meta;
-        if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
-            process.stderr.write(`warning: artifact schema ${name} is missing meta; expected v3 schema version ${EXPECTED_ARTIFACT_SCHEMA_VERSION}\n`);
+}
+/**
+ * Full schema-meta index over an artifact schemas directory. Emits malformed-meta
+ * and version-mismatch warnings for every schema file; the full loader relies on
+ * this strict coverage to surface drift across the whole identity set.
+ */
+function schemaMetas(dir) {
+    const metas = new Map();
+    for (const name of listSchemaFiles(dir)) {
+        const meta = readSchemaMeta(path.join(dir, name));
+        if (!meta) {
+            warnMalformedSchemaMeta(name);
             continue;
         }
-        const m = meta;
-        const version = String(m.version ?? "").trim();
-        if (!version || version !== EXPECTED_ARTIFACT_SCHEMA_VERSION) {
-            const reported = version || "(missing)";
-            process.stderr.write(`warning: artifact schema ${name} version ${reported} does not match expected v3 schema version ${EXPECTED_ARTIFACT_SCHEMA_VERSION}\n`);
-        }
-        const artifactId = String(m.name ?? "").trim();
+        warnSchemaVersionMismatch(meta, name);
+        const artifactId = String(meta.name ?? "").trim();
         if (artifactId) {
-            metas.set(artifactId, m);
+            metas.set(artifactId, meta);
         }
     }
     return metas;
 }
+/**
+ * Targeted schema-meta lookup for a single artifact identity. Walks the schemas
+ * directory only to find the file whose `meta.name` matches `artifactId`, and
+ * emits warnings only for that schema. Unrelated malformed or version-mismatched
+ * schemas in the same directory stay silent so callers resolving a single
+ * identity (e.g. `profile`) don't fan out noise across the required-identity set.
+ */
+function loadSchemaMetaForArtifact(dir, artifactId) {
+    for (const name of listSchemaFiles(dir)) {
+        let meta;
+        try {
+            meta = readSchemaMeta(path.join(dir, name));
+        }
+        catch {
+            continue;
+        }
+        if (!meta)
+            continue;
+        if (String(meta.name ?? "").trim() !== artifactId)
+            continue;
+        warnSchemaVersionMismatch(meta, name);
+        return meta;
+    }
+    return null;
+}
+function findRequiredIdentity(model, artifactId) {
+    const identities = (model.required_artifact_identities ?? {});
+    for (const [scope, identityList] of Object.entries(identities)) {
+        if (!Array.isArray(identityList))
+            continue;
+        for (const identity of identityList) {
+            if (!identity || typeof identity !== "object" || Array.isArray(identity))
+                continue;
+            const id = identity;
+            if (String(id.artifact_id ?? "").trim() === artifactId) {
+                return { scope, identity: id };
+            }
+        }
+    }
+    return null;
+}
+function findSpecialCase(model, artifactId) {
+    const specialCases = (model.explicit_special_cases ?? []);
+    for (const special of specialCases) {
+        if (!special || typeof special !== "object" || Array.isArray(special))
+            continue;
+        const sp = special;
+        if (String(sp.artifact_id ?? "").trim() === artifactId) {
+            return sp;
+        }
+    }
+    return null;
+}
+function buildRequiredRecord(scope, identity, meta) {
+    const template = identity.path_template;
+    return {
+        artifactId: String(identity.artifact_id ?? "").trim(),
+        displayName: String(identity.display_name ?? "").trim(),
+        defaultPath: normalizePath(String(identity.default_path ?? meta.path ?? "")),
+        producers: asSet(meta.producer),
+        consumers: asSet(meta.consumers),
+        artifactType: String(meta.artifact_type ?? "").trim(),
+        scope: String(scope),
+        pathTemplate: template && typeof template === "object" && !Array.isArray(template)
+            ? template
+            : null,
+        docsYamlCanOverridePath: true,
+        implementationStatus: String(meta.implementation_status ?? "implemented").trim(),
+    };
+}
+function buildSpecialCaseRecord(sp) {
+    const template = sp.path_template;
+    return {
+        artifactId: String(sp.artifact_id ?? "").trim(),
+        displayName: String(sp.display_name ?? "").trim(),
+        defaultPath: normalizePath(String(sp.default_path ?? "")),
+        producers: asSet(sp.producers),
+        consumers: asSet(sp.consumers),
+        artifactType: String(sp.artifact_type ?? "").trim(),
+        scope: String(sp.scope ?? "").trim(),
+        pathTemplate: template && typeof template === "object" && !Array.isArray(template)
+            ? template
+            : null,
+        docsYamlCanOverridePath: Boolean(sp.docs_yaml_can_override_path),
+        implementationStatus: String(sp.implementation_status ?? "implemented").trim(),
+    };
+}
 export function loadArtifactRegistry(artifactSchemasDirPath = artifactSchemasDir(), registryModelPathArg = registryModelPath()) {
     const model = loadYaml(registryModelPathArg);
     const metas = schemaMetas(artifactSchemasDirPath);
@@ -120,20 +226,7 @@ export function loadArtifactRegistry(artifactSchemasDirPath = artifactSchemasDir
                 process.stderr.write(`warning: required artifact identity '${artifactId}' has no matching schema file in ${artifactSchemasDirPath}\n`);
                 continue;
             }
-            const template = id.path_template;
-            records.set(artifactId, {
-                artifactId,
-                displayName: String(id.display_name ?? "").trim(),
-                defaultPath: normalizePath(String(id.default_path ?? meta.path ?? "")),
-                producers: asSet(meta.producer),
-                consumers: asSet(meta.consumers),
-                artifactType: String(meta.artifact_type ?? "").trim(),
-                scope: String(scope),
-                pathTemplate: template && typeof template === "object" && !Array.isArray(template)
-                    ? template
-                    : null,
-                docsYamlCanOverridePath: true,
-            });
+            records.set(artifactId, buildRequiredRecord(scope, id, meta));
         }
     }
     const specialCases = (model.explicit_special_cases ?? []);
@@ -146,57 +239,109 @@ export function loadArtifactRegistry(artifactSchemasDirPath = artifactSchemasDir
         if (!artifactId) {
             continue;
         }
-        const template = sp.path_template;
-        records.set(artifactId, {
-            artifactId,
-            displayName: String(sp.display_name ?? "").trim(),
-            defaultPath: normalizePath(String(sp.default_path ?? "")),
-            producers: asSet(sp.producers),
-            consumers: asSet(sp.consumers),
-            artifactType: String(sp.artifact_type ?? "").trim(),
-            scope: String(sp.scope ?? "").trim(),
-            pathTemplate: template && typeof template === "object" && !Array.isArray(template)
-                ? template
-                : null,
-            docsYamlCanOverridePath: Boolean(sp.docs_yaml_can_override_path),
-        });
+        records.set(artifactId, buildSpecialCaseRecord(sp));
     }
     return records;
 }
-export function loadDocsPathOverrides(projectRoot) {
-    const docsPath = path.join(projectRoot, ".agentera", "docs.yaml");
-    if (!fs.existsSync(docsPath)) {
-        return {};
+/**
+ * Targeted lookup of a single artifact record. Resolves against the same
+ * model/schema authority as `loadArtifactRegistry` but inspects only the
+ * requested identity, so a special case such as `profile` loads without
+ * walking or warning about unrelated required schemas. A requested required
+ * identity still warns and returns `undefined` when its matching schema file is
+ * missing from the schemas directory.
+ */
+export function loadArtifactRecord(artifactId, artifactSchemasDirPath = artifactSchemasDir(), registryModelPathArg = registryModelPath()) {
+    const model = loadYaml(registryModelPathArg);
+    const specialCase = findSpecialCase(model, artifactId);
+    if (specialCase) {
+        return buildSpecialCaseRecord(specialCase);
+    }
+    const required = findRequiredIdentity(model, artifactId);
+    if (!required) {
+        return undefined;
     }
+    const meta = loadSchemaMetaForArtifact(artifactSchemasDirPath, artifactId);
+    if (!meta) {
+        process.stderr.write(`warning: required artifact identity '${artifactId}' has no matching schema file in ${artifactSchemasDirPath}\n`);
+        return undefined;
+    }
+    return buildRequiredRecord(required.scope, required.identity, meta);
+}
+export function docsPathOverridesFromBytes(bytes, strict = false) {
     let data;
     try {
-        data = loadYamlMapping(fs.readFileSync(docsPath, "utf8"));
+        data = loadYamlMapping(bytes.toString());
     }
     catch (exc) {
+        if (strict)
+            throw new Error(`failed to load docs path overrides: ${exc.message}`);
         process.stderr.write(`warning: failed to load docs path overrides: ${exc.message}\n`);
         return {};
     }
     const mapping = data.mapping;
     if (!Array.isArray(mapping)) {
+        if (strict && mapping !== undefined)
+            throw new Error("failed to load docs path overrides: mapping must be a list");
         return {};
     }
     const overrides = {};
     for (const entry of mapping) {
         if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            if (strict)
+                throw new Error("failed to load docs path overrides: every mapping entry must be a mapping");
             continue;
         }
         const e = entry;
-        const artifact = e.artifact;
-        const p = e.path;
-        if (typeof artifact === "string" && typeof p === "string") {
-            overrides[artifact] = p;
-        }
+        if (typeof e.artifact === "string" && typeof e.path === "string")
+            overrides[e.artifact] = e.path;
+        else if (strict)
+            throw new Error("failed to load docs path overrides: every mapping entry requires string artifact and path fields");
     }
     return overrides;
 }
-export function resolveArtifactPath(record, projectRoot, activeObjectiveName = null, env = process.env) {
+export function loadDocsPathOverrides(projectRoot, strict = false) {
+    const docsPath = path.join(projectRoot, ARTIFACT_PROTOCOL_PATHS.docs);
+    if (!fs.existsSync(docsPath)) {
+        return {};
+    }
+    let bytes;
+    try {
+        bytes = fs.readFileSync(docsPath);
+    }
+    catch (exc) {
+        if (strict)
+            throw new Error(`failed to load docs path overrides: ${exc.message}`);
+        process.stderr.write(`warning: failed to load docs path overrides: ${exc.message}\n`);
+        return {};
+    }
+    return docsPathOverridesFromBytes(bytes, strict);
+}
+function nearestExistingAncestor(p) {
+    let current = p;
+    while (!fs.existsSync(current)) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return fs.realpathSync.native(current);
+}
+export function assertRealpathBoundary(projectRoot, artifactPath, artifactId) {
+    const projectReal = nearestExistingAncestor(resolvePath(projectRoot));
+    const ancestorReal = nearestExistingAncestor(artifactPath);
+    const rel = path.relative(projectReal, ancestorReal);
+    if (rel !== "" && (rel.startsWith("..") || path.isAbsolute(rel))) {
+        throw new Error(`artifact '${artifactId}' path escapes the project boundary`);
+    }
+}
+export function resolveArtifactPath(record, projectRoot, activeObjectiveNameOrOptions = null, env = process.env) {
+    const options = typeof activeObjectiveNameOrOptions === "object" && activeObjectiveNameOrOptions !== null
+        ? activeObjectiveNameOrOptions
+        : { activeObjectiveName: activeObjectiveNameOrOptions };
+    const activeObjectiveName = options.activeObjectiveName ?? null;
     let artifactPath = record.defaultPath;
-    const overrides = loadDocsPathOverrides(projectRoot);
+    const overrides = options.docsPathOverrides ?? loadDocsPathOverrides(projectRoot, options.strictWrite === true);
     if (record.docsYamlCanOverridePath && record.displayName in overrides) {
         artifactPath = overrides[record.displayName];
     }
@@ -215,6 +360,8 @@ export function resolveArtifactPath(record, projectRoot, activeObjectiveName = n
             return path.join(base, suffix);
         }
     }
-    return projectPath(projectRoot, artifactPath, record.artifactId);
+    const resolved = projectPath(projectRoot, artifactPath, record.artifactId);
+    if (options.strictWrite)
+        assertRealpathBoundary(projectRoot, resolved, record.artifactId);
+    return resolved;
 }
-//# sourceMappingURL=artifactRegistry.js.map

package/dist/registries/artifactSchemaProjection.js

@@ -0,0 +1,45 @@
+const FIELD_SKIP = new Set([
+    "meta",
+    "GROUP_PREFIXES",
+    "BUDGET",
+    "COMPACTION",
+    "VALIDATION",
+    "ARCHIVE",
+    "CONVENTION",
+    "CONVENTIONS",
+]);
+function mapping(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+export function artifactSchemaFieldDescription(entry, group) {
+    return {
+        id: entry.id ?? null,
+        group,
+        field: entry.field ?? null,
+        ...(typeof entry.path === "string" ? { path: entry.path } : {}),
+        type: entry.type ?? "unknown",
+        required: "required" in entry ? entry.required : "unknown",
+        format: entry.format ?? null,
+        validation: entry.validation ?? [],
+        ...(entry.accepted_forms !== undefined ? { accepted_forms: structuredClone(entry.accepted_forms) } : {}),
+        ...(entry.normalization !== undefined ? { normalization: structuredClone(entry.normalization) } : {}),
+        ...(entry.write_operations !== undefined ? { write_operations: structuredClone(entry.write_operations) } : {}),
+    };
+}
+export function describeArtifactSchemaFields(schema) {
+    const fields = [];
+    for (const [group, value] of Object.entries(schema)) {
+        if (FIELD_SKIP.has(group) || !mapping(value))
+            continue;
+        for (const entry of Object.values(value)) {
+            if (mapping(entry) && "field" in entry)
+                fields.push(artifactSchemaFieldDescription(entry, group));
+        }
+    }
+    return fields;
+}
+export function artifactSchemaFieldsForOperation(schema, verb) {
+    if (!schema)
+        return [];
+    return describeArtifactSchemaFields(schema).filter((field) => Array.isArray(field.write_operations) && field.write_operations.includes(verb));
+}

package/dist/registries/capabilityContract.js

@@ -106,16 +106,11 @@ export function buildCapabilitySchemaContract(data, contractPath) {
 }
 function buildTriggerEnrichmentRules(data) {
     const enrichment = data.TRIGGER_ENRICHMENT;
-    const defaults = enrichment.contract_defaults;
     const fields = enrichment.fields;
     const primaryAliases = data.ROUTE_ALIASES.primary_aliases;
     const allowedCapabilityIds = primaryAliases.map((entry) => entry.capability);
     return {
         spec: enrichment.spec,
-        contractDefaults: {
-            confidenceThreshold: defaults.confidence_threshold,
-            borderlineBand: defaults.borderline_band,
-        },
         fields: Object.fromEntries(Object.entries(fields).map(([name, raw]) => [name, buildEnrichmentFieldRule(raw)])),
         allowedCapabilityIds,
     };
@@ -355,9 +350,7 @@ function checkSelfGroups(data, sourceLabel, requiredGroups, errors) {
     }
 }
 /**
- * Required integer range field inside TRIGGER_ENRICHMENT (defaults and
- * per-field min/max). Used by both the contract_defaults and field-level
- * constraint checks below.
+ * Required integer range field inside TRIGGER_ENRICHMENT compatibility rules.
  */
 function checkEnrichmentIntegerField(value, label, sourceLabel, errors) {
     if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 100) {
@@ -373,22 +366,15 @@ function checkTriggerEnrichmentRules(data, sourceLabel, errors) {
     if (typeof enrichment.spec !== "string" || !enrichment.spec) {
         errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.spec in ${sourceLabel} must be a non-empty string`);
     }
-    const defaults = enrichment.contract_defaults;
-    if (!isMapping(defaults)) {
-        errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.contract_defaults in ${sourceLabel} must be a mapping`);
-    }
-    else {
-        checkEnrichmentIntegerField(defaults.confidence_threshold, "TRIGGER_ENRICHMENT.contract_defaults.confidence_threshold", sourceLabel, errors);
-        checkEnrichmentIntegerField(defaults.borderline_band, "TRIGGER_ENRICHMENT.contract_defaults.borderline_band", sourceLabel, errors);
-    }
     const fields = enrichment.fields;
     if (!isMapping(fields)) {
         errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields in ${sourceLabel} must be a mapping`);
         return;
     }
-    // The four canonical enrichment field names. Each must exist as a mapping
-    // with the documented shape; the loader reads them faithfully.
+    // Legacy fields remain shape-validated for compatibility, but are not
+    // carried into the active semantic trigger model.
     const expected = {
+        patterns: "list_of_strings",
         confidence_threshold: "integer",
         borderline_band: "integer",
         patterns_regex: "list_of_strings",
@@ -414,9 +400,8 @@ function checkTriggerEnrichmentRules(data, sourceLabel, errors) {
             if (typeof max !== "number" || max !== 100) {
                 errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName}.max in ${sourceLabel} must be 100`);
             }
-            checkEnrichmentIntegerField(fields[fieldName].default, `TRIGGER_ENRICHMENT.fields.${fieldName}.default`, sourceLabel, errors);
         }
-        if (expectedType === "list_of_strings" && fields[fieldName].each_must_be_valid_regex !== true) {
+        if (fieldName === "patterns_regex" && fields[fieldName].each_must_be_valid_regex !== true) {
             errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName}.each_must_be_valid_regex in ${sourceLabel} must be true`);
         }
     }
@@ -451,4 +436,3 @@ function checkTriggerEnrichmentRules(data, sourceLabel, errors) {
         }
     }
 }
-//# sourceMappingURL=capabilityContract.js.map

package/dist/registries/evaluatorHandoffContract.js

@@ -168,4 +168,3 @@ export function evaluatorHandoffOutputRequirements(contract) {
         schema_authority: "references/cli/capability-instruction-contract.yaml#evaluator_handoff",
     };
 }
-//# sourceMappingURL=evaluatorHandoffContract.js.map