@metaobjectsdev/sdk 0.23.1 → 0.24.0

package/dist/records/any.d.ts

@@ -127,6 +127,7 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     scope: z.ZodUnion<[z.ZodLiteral<"global">, z.ZodArray<z.ZodString, "many">]>;
 }, "strip", z.ZodTypeAny, {
     type: "decision";
+    scope: string[] | "global";
     schema_version: 1;
     id: string;
     title: string;
@@ -141,7 +142,6 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     }[];
     rationale: string;
     alternatives_considered: string[];
-    scope: string[] | "global";
     superseded_by?: string | undefined;
     evidence?: {
         commits?: string[] | undefined;
@@ -150,6 +150,7 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     } | undefined;
 }, {
     type: "decision";
+    scope: string[] | "global";
     schema_version: 1;
     id: string;
     title: string;
@@ -159,7 +160,6 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     last_validated_against_commit: string;
     rationale: string;
     alternatives_considered: string[];
-    scope: string[] | "global";
     superseded_by?: string | undefined;
     evidence?: {
         commits?: string[] | undefined;
@@ -216,6 +216,7 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     enforcement: z.ZodDefault<z.ZodEnum<["advisory", "block"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "principle";
+    scope: string[];
     schema_version: 1;
     id: string;
     title: string;
@@ -230,7 +231,6 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     }[];
     examples: string[];
     rationale: string;
-    scope: string[];
     statement: string;
     counter_examples: string[];
     enforcement: "advisory" | "block";
@@ -242,6 +242,7 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     } | undefined;
 }, {
     type: "principle";
+    scope: string[];
     schema_version: 1;
     id: string;
     title: string;
@@ -251,7 +252,6 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     last_validated_against_commit: string;
     examples: string[];
     rationale: string;
-    scope: string[];
     statement: string;
     counter_examples: string[];
     superseded_by?: string | undefined;
@@ -310,11 +310,11 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         entity: z.ZodOptional<z.ZodString>;
         files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
-        entity?: string | undefined;
         files?: string[] | undefined;
-    }, {
         entity?: string | undefined;
+    }, {
         files?: string[] | undefined;
+        entity?: string | undefined;
     }>;
     see_also: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -335,8 +335,8 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     synonyms: string[];
     definition: string;
     code_anchors: {
-        entity?: string | undefined;
         files?: string[] | undefined;
+        entity?: string | undefined;
     };
     see_also: string[];
     superseded_by?: string | undefined;
@@ -358,8 +358,8 @@ export declare const AnyRecord: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     synonyms: string[];
     definition: string;
     code_anchors: {
-        entity?: string | undefined;
         files?: string[] | undefined;
+        entity?: string | undefined;
     };
     see_also: string[];
     superseded_by?: string | undefined;

package/dist/records/decision.d.ts

@@ -41,6 +41,7 @@ export declare const DecisionRecord: z.ZodObject<{
     scope: z.ZodUnion<[z.ZodLiteral<"global">, z.ZodArray<z.ZodString, "many">]>;
 }, "strip", z.ZodTypeAny, {
     type: "decision";
+    scope: string[] | "global";
     schema_version: 1;
     id: string;
     title: string;
@@ -55,7 +56,6 @@ export declare const DecisionRecord: z.ZodObject<{
     }[];
     rationale: string;
     alternatives_considered: string[];
-    scope: string[] | "global";
     superseded_by?: string | undefined;
     evidence?: {
         commits?: string[] | undefined;
@@ -64,6 +64,7 @@ export declare const DecisionRecord: z.ZodObject<{
     } | undefined;
 }, {
     type: "decision";
+    scope: string[] | "global";
     schema_version: 1;
     id: string;
     title: string;
@@ -73,7 +74,6 @@ export declare const DecisionRecord: z.ZodObject<{
     last_validated_against_commit: string;
     rationale: string;
     alternatives_considered: string[];
-    scope: string[] | "global";
     superseded_by?: string | undefined;
     evidence?: {
         commits?: string[] | undefined;

package/dist/records/glossary.d.ts

@@ -43,11 +43,11 @@ export declare const GlossaryRecord: z.ZodObject<{
         entity: z.ZodOptional<z.ZodString>;
         files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
-        entity?: string | undefined;
         files?: string[] | undefined;
-    }, {
         entity?: string | undefined;
+    }, {
         files?: string[] | undefined;
+        entity?: string | undefined;
     }>;
     see_also: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -68,8 +68,8 @@ export declare const GlossaryRecord: z.ZodObject<{
     synonyms: string[];
     definition: string;
     code_anchors: {
-        entity?: string | undefined;
         files?: string[] | undefined;
+        entity?: string | undefined;
     };
     see_also: string[];
     superseded_by?: string | undefined;
@@ -91,8 +91,8 @@ export declare const GlossaryRecord: z.ZodObject<{
     synonyms: string[];
     definition: string;
     code_anchors: {
-        entity?: string | undefined;
         files?: string[] | undefined;
+        entity?: string | undefined;
     };
     see_also: string[];
     superseded_by?: string | undefined;

package/dist/records/principle.d.ts

@@ -44,6 +44,7 @@ export declare const PrincipleRecord: z.ZodObject<{
     enforcement: z.ZodDefault<z.ZodEnum<["advisory", "block"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "principle";
+    scope: string[];
     schema_version: 1;
     id: string;
     title: string;
@@ -58,7 +59,6 @@ export declare const PrincipleRecord: z.ZodObject<{
     }[];
     examples: string[];
     rationale: string;
-    scope: string[];
     statement: string;
     counter_examples: string[];
     enforcement: "advisory" | "block";
@@ -70,6 +70,7 @@ export declare const PrincipleRecord: z.ZodObject<{
     } | undefined;
 }, {
     type: "principle";
+    scope: string[];
     schema_version: 1;
     id: string;
     title: string;
@@ -79,7 +80,6 @@ export declare const PrincipleRecord: z.ZodObject<{
     last_validated_against_commit: string;
     examples: string[];
     rationale: string;
-    scope: string[];
     statement: string;
     counter_examples: string[];
     superseded_by?: string | undefined;

package/dist/scope.d.ts

@@ -0,0 +1,16 @@
+/** A consumer-side output filter over fully-qualified node names. */
+export interface Scope {
+    /** Absent or empty means "everything". */
+    readonly include?: readonly string[];
+    /** Applied after `include`. */
+    readonly exclude?: readonly string[];
+}
+export interface CompiledScope {
+    readonly include: readonly RegExp[];
+    readonly exclude: readonly RegExp[];
+}
+export declare function compilePattern(pattern: string): RegExp;
+export declare function compileScope(scope: Scope): CompiledScope;
+/** True when `fqn` is inside the scope. An empty `include` means everything. */
+export declare function matchesScope(fqn: string, compiled: CompiledScope): boolean;
+//# sourceMappingURL=scope.d.ts.map

package/dist/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAkBA,qEAAqE;AACrE,MAAM,WAAW,KAAK;IACpB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAuCD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAYtD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,CAKxD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAI1E"}

package/dist/scope.js

@@ -0,0 +1,75 @@
+// server/typescript/packages/sdk/src/scope.ts
+//
+// Phase-1 metadata-source-resolution — the scope pattern engine.
+//
+// A pure, no-I/O module deciding whether a fully-qualified node name falls
+// inside a consumer's declared `include`/`exclude` scope. Source resolution
+// and discovery (later phase-1 tasks) build on this; a cross-language
+// conformance corpus pins its semantics, so exact pattern behavior matters.
+// NOTE: PACKAGE_SEPARATOR is NOT re-exported from the browser-safe
+// `@metaobjectsdev/metadata/constants` barrel (that barrel only re-exports
+// the per-concern `*-constants.ts` modules; `PACKAGE_SEPARATOR` lives in
+// `shared/structural.ts`, exported from the package root). This package
+// (`@metaobjectsdev/sdk`) is server-side, not a `client/web/**` browser
+// package, so importing metamodel values from the root — the same thing
+// `memory.ts` and `forge-types.ts` in this package already do — is correct.
+import { PACKAGE_SEPARATOR, ParseError, codeSource } from "@metaobjectsdev/metadata";
+/** One package segment: any run of characters containing no separator char. */
+const SEGMENT = "[^:]+";
+/** One or more segments, separator-joined — the `**` expansion. */
+const SEGMENTS = `${SEGMENT}(?:${PACKAGE_SEPARATOR}${SEGMENT})*`;
+function escapeLiteral(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Compile one segment. `**` spans segments; `*` never crosses a separator. */
+function compileSegment(segment, pattern) {
+    if (segment.length === 0) {
+        throw new ParseError(`empty segment in scope pattern "${pattern}"`, {
+            code: "ERR_SCOPE_PATTERN_INVALID",
+            source: codeSource("compileSegment"),
+        });
+    }
+    // A segment surviving the split on the two-character PACKAGE_SEPARATOR
+    // ("::") can still contain a lone ":" when the pattern has an odd colon
+    // run — e.g. "acme:::Order".split("::") => ["acme", ":Order"]. SEGMENT
+    // ([^:]+) already excludes ":" from a well-formed segment, so a leftover
+    // ":" here means the separator was malformed, not that ":" is meant
+    // literally. Left unchecked, escapeLiteral treats it as a literal
+    // character and compiles a regex requiring three colons in a row — which
+    // no legal "::"-joined fully-qualified name can ever contain, so the
+    // pattern silently matches nothing instead of failing loud.
+    if (segment.includes(":")) {
+        throw new ParseError(`scope pattern "${pattern}" has a malformed separator (an odd run of ":") — segments are joined by "::", never a single ":"`, { code: "ERR_SCOPE_PATTERN_INVALID", source: codeSource("compileSegment") });
+    }
+    if (segment === "**")
+        return `(?:${SEGMENTS})`;
+    // `*` inside a segment matches any characters except the separator char.
+    return segment.split("*").map(escapeLiteral).join("[^:]*");
+}
+export function compilePattern(pattern) {
+    if (pattern.length === 0) {
+        throw new ParseError(`scope pattern must not be empty`, {
+            code: "ERR_SCOPE_PATTERN_INVALID",
+            source: codeSource("compilePattern"),
+        });
+    }
+    const body = pattern
+        .split(PACKAGE_SEPARATOR)
+        .map((segment) => compileSegment(segment, pattern))
+        .join(PACKAGE_SEPARATOR);
+    return new RegExp(`^${body}$`);
+}
+export function compileScope(scope) {
+    return {
+        include: (scope.include ?? []).map(compilePattern),
+        exclude: (scope.exclude ?? []).map(compilePattern),
+    };
+}
+/** True when `fqn` is inside the scope. An empty `include` means everything. */
+export function matchesScope(fqn, compiled) {
+    const included = compiled.include.length === 0 || compiled.include.some((re) => re.test(fqn));
+    if (!included)
+        return false;
+    return !compiled.exclude.some((re) => re.test(fqn));
+}
+//# sourceMappingURL=scope.js.map

package/dist/scope.js.map

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

package/dist/sources.d.ts

@@ -0,0 +1,86 @@
+/** Tagged union of source kinds. `resource` and `package` are declared now so
+ *  the config shape is stable across phases; only `path` resolves in phase 1 —
+ *  `resource`/`package` throw `ERR_SOURCE_KIND_UNSUPPORTED`. */
+export type SourceSpec = {
+    readonly path: string;
+} | {
+    readonly resource: string;
+} | {
+    readonly package: string;
+};
+export interface ResolvedSource {
+    /** Absolute path of one metadata file. */
+    readonly file: string;
+    /** The spec that contributed it — provenance for diagnostics. */
+    readonly spec: SourceSpec;
+}
+/** Used when `sources` is absent or empty in `.metaobjects/config.json`. A
+ *  DEFAULT, never a requirement — a project that declares `sources` explicitly
+ *  need not include the default directory at all. Built from
+ *  `DEFAULT_METADATA_DIR` (`metadata-files.ts`'s single definition) rather than
+ *  restating that name here: a second independent encoding of the same
+ *  default would let `resolveCollection`'s "does the default dir exist"
+ *  check (`collection.ts`) desync from what `resolveSources` actually
+ *  resolves the moment the default ever changed — silently reproducing the
+ *  "two code paths disagree about where metadata lives" class of bug this
+ *  whole mechanism exists to eliminate. */
+export declare const DEFAULT_SOURCES: readonly SourceSpec[];
+/**
+ * The declared source SET in CANONICAL order — kind-validated, then sorted by
+ * spec CONTENT rather than by declaration order.
+ *
+ * This is the ONE place declaration order is discarded, and the module's "pure
+ * function of the SET" invariant rests on it: the emitted file order, the spec
+ * attributed to a file two specs both reach, and which of several unresolvable
+ * paths reports its `ERR_SOURCE_UNRESOLVED` first are all decided here.
+ * Validation runs across the WHOLE list before any sorting or filesystem I/O —
+ * interleaved with resolution, which error code came back would depend on
+ * declaration order, contradicting that same invariant.
+ *
+ * Exported because `resolveCollection` derives `sourceRoots` from the declared
+ * specs and must use this identical ordering; a second sort would be a second
+ * definition of "canonical".
+ */
+export declare function orderedPathSpecs(specs: readonly SourceSpec[]): {
+    readonly path: string;
+}[];
+/**
+ * Where a declared `path` source lives on disk: absolute as written, otherwise
+ * relative to the DECLARING config's directory — never to ambient
+ * `process.cwd()`.
+ *
+ * One definition, because this expression *is* the rule for where a declared
+ * source lives, which is the single piece of knowledge this module exists to
+ * own. A caller that needs a source's root directory (rather than its files)
+ * calls this rather than restating it.
+ */
+export declare function resolveSpecPath(configDir: string, spec: {
+    readonly path: string;
+}): string;
+/**
+ * Resolve a declared source SET to a canonically-ordered list of metadata files.
+ *
+ * The full result — each entry's `.file` AND its `.spec` — is a pure function
+ * of the SET of `specs`: permuting `specs` cannot change the output. One thing
+ * makes that hold: the specs are processed in CONTENT order
+ * (`JSON.stringify(spec)`, ascending) rather than declared order, so both the
+ * emitted file order and the spec attributed to a file overlapping two specs
+ * are decided by content alone. Declared order carries no information anywhere
+ * in this function.
+ *
+ * Within one directory spec the file order is `listMetadataFiles`'s — files at
+ * a level, then that level's subdirectories, depth-first. That is deliberately
+ * NOT a flat sort of absolute paths: see the file header, and
+ * `test/source-order.test.ts`.
+ *
+ * Only `path` specs resolve in phase 1: a directory is walked recursively, a
+ * file is taken as-is. An unresolvable `path` throws `ERR_SOURCE_UNRESOLVED`
+ * rather than silently contributing nothing; `resource`/`package` specs throw
+ * `ERR_SOURCE_KIND_UNSUPPORTED`.
+ *
+ * @param configDir absolute directory of the declaring config (the parent of
+ *   `.metaobjects/`) — relative `path` specs resolve against it, never against
+ *   ambient `process.cwd()`.
+ */
+export declare function resolveSources(configDir: string, specs: readonly SourceSpec[]): Promise<ResolvedSource[]>;
+//# sourceMappingURL=sources.d.ts.map

package/dist/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AA2BA;;gEAEgE;AAChE,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED;;;;;;;;;2CAS2C;AAC3C,eAAO,MAAM,eAAe,EAAE,SAAS,UAAU,EAAqC,CAAC;AAgBvF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAK1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,OAAO,CAAC,cAAc,EAAE,CAAC,CA0B3B"}

package/dist/sources.js

@@ -0,0 +1,130 @@
+// server/typescript/packages/sdk/src/sources.ts
+//
+// Phase-1 metadata-source-resolution — source spec resolution.
+//
+// Turns a declared source SET (`.metaobjects/config.json`'s `sources`) into a
+// canonically-ordered, de-duplicated list of metadata file paths. The FULL
+// result — including which spec each entry attributes to — is a pure
+// function of the source SET, never of declaration order: permuting `specs`
+// cannot change the output, even when two specs overlap on the same file.
+// `test/order-independence.test.ts` pins that (the design's linchpin), so the
+// canonical spec ordering below is load-bearing.
+//
+// Canonical is NOT the same as "flat-sorted". Within one directory spec the
+// order is `listMetadataFiles`'s (metadata-files.ts) — files at a level, then
+// that level's subdirectories, depth-first — because that is the order production
+// has always handed the loader, and declaration order survives into generated
+// output (the barrel's export list, the shared `enums.ts`, `meta docs` page
+// order, `meta export`'s sibling order). A flat sort of absolute paths
+// silently reorders any project with a subdirectory whose name sorts before a
+// sibling file. Across specs, order is decided by spec CONTENT, which is what
+// keeps the whole result permutation-invariant. `test/source-order.test.ts`
+// pins both halves.
+import { stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { ParseError, codeSource } from "@metaobjectsdev/metadata";
+import { DEFAULT_METADATA_DIR, listMetadataFiles } from "./metadata-files.js";
+/** Used when `sources` is absent or empty in `.metaobjects/config.json`. A
+ *  DEFAULT, never a requirement — a project that declares `sources` explicitly
+ *  need not include the default directory at all. Built from
+ *  `DEFAULT_METADATA_DIR` (`metadata-files.ts`'s single definition) rather than
+ *  restating that name here: a second independent encoding of the same
+ *  default would let `resolveCollection`'s "does the default dir exist"
+ *  check (`collection.ts`) desync from what `resolveSources` actually
+ *  resolves the moment the default ever changed — silently reproducing the
+ *  "two code paths disagree about where metadata lives" class of bug this
+ *  whole mechanism exists to eliminate. */
+export const DEFAULT_SOURCES = [{ path: DEFAULT_METADATA_DIR }];
+/** Narrows `spec` to its `path` arm, throwing `ERR_SOURCE_KIND_UNSUPPORTED`
+ *  for `resource`/`package` — phase 1 resolves `path` only. Returns rather than
+ *  asserting so one call both validates and narrows: an `asserts` signature has
+ *  to be re-invoked wherever TypeScript's control-flow analysis cannot carry the
+ *  narrowing, which is a language workaround masquerading as a second check. */
+function toPathSpec(spec) {
+    if ("path" in spec)
+        return spec;
+    const kind = "resource" in spec ? "resource" : "package";
+    throw new ParseError(`source kind "${kind}" is not supported by this toolchain yet; use a "path" source`, { code: "ERR_SOURCE_KIND_UNSUPPORTED", source: codeSource("resolveSources") });
+}
+/**
+ * The declared source SET in CANONICAL order — kind-validated, then sorted by
+ * spec CONTENT rather than by declaration order.
+ *
+ * This is the ONE place declaration order is discarded, and the module's "pure
+ * function of the SET" invariant rests on it: the emitted file order, the spec
+ * attributed to a file two specs both reach, and which of several unresolvable
+ * paths reports its `ERR_SOURCE_UNRESOLVED` first are all decided here.
+ * Validation runs across the WHOLE list before any sorting or filesystem I/O —
+ * interleaved with resolution, which error code came back would depend on
+ * declaration order, contradicting that same invariant.
+ *
+ * Exported because `resolveCollection` derives `sourceRoots` from the declared
+ * specs and must use this identical ordering; a second sort would be a second
+ * definition of "canonical".
+ */
+export function orderedPathSpecs(specs) {
+    return specs.map(toPathSpec).sort((a, b) => {
+        const [ja, jb] = [JSON.stringify(a), JSON.stringify(b)];
+        return ja < jb ? -1 : ja > jb ? 1 : 0;
+    });
+}
+/**
+ * Where a declared `path` source lives on disk: absolute as written, otherwise
+ * relative to the DECLARING config's directory — never to ambient
+ * `process.cwd()`.
+ *
+ * One definition, because this expression *is* the rule for where a declared
+ * source lives, which is the single piece of knowledge this module exists to
+ * own. A caller that needs a source's root directory (rather than its files)
+ * calls this rather than restating it.
+ */
+export function resolveSpecPath(configDir, spec) {
+    return isAbsolute(spec.path) ? spec.path : resolve(configDir, spec.path);
+}
+/**
+ * Resolve a declared source SET to a canonically-ordered list of metadata files.
+ *
+ * The full result — each entry's `.file` AND its `.spec` — is a pure function
+ * of the SET of `specs`: permuting `specs` cannot change the output. One thing
+ * makes that hold: the specs are processed in CONTENT order
+ * (`JSON.stringify(spec)`, ascending) rather than declared order, so both the
+ * emitted file order and the spec attributed to a file overlapping two specs
+ * are decided by content alone. Declared order carries no information anywhere
+ * in this function.
+ *
+ * Within one directory spec the file order is `listMetadataFiles`'s — files at
+ * a level, then that level's subdirectories, depth-first. That is deliberately
+ * NOT a flat sort of absolute paths: see the file header, and
+ * `test/source-order.test.ts`.
+ *
+ * Only `path` specs resolve in phase 1: a directory is walked recursively, a
+ * file is taken as-is. An unresolvable `path` throws `ERR_SOURCE_UNRESOLVED`
+ * rather than silently contributing nothing; `resource`/`package` specs throw
+ * `ERR_SOURCE_KIND_UNSUPPORTED`.
+ *
+ * @param configDir absolute directory of the declaring config (the parent of
+ *   `.metaobjects/`) — relative `path` specs resolve against it, never against
+ *   ambient `process.cwd()`.
+ */
+export async function resolveSources(configDir, specs) {
+    // Kind-validated and content-ordered in one pass — see `orderedPathSpecs`.
+    const ordered = orderedPathSpecs(specs);
+    // Insertion order IS output order — a Map preserves it, so the per-spec walk
+    // order above survives to the caller. First contributor wins a shared file,
+    // which is content-determined because `ordered` is.
+    const byFile = new Map();
+    for (const spec of ordered) {
+        const target = resolveSpecPath(configDir, spec);
+        const stats = await stat(target).catch(() => undefined);
+        if (stats === undefined) {
+            throw new ParseError(`source path "${spec.path}" does not exist (resolved to ${target}, relative to ${configDir})`, { code: "ERR_SOURCE_UNRESOLVED", source: codeSource("resolveSources") });
+        }
+        const found = stats.isDirectory() ? await listMetadataFiles(target) : [target];
+        for (const file of found) {
+            if (!byFile.has(file))
+                byFile.set(file, spec);
+        }
+    }
+    return [...byFile].map(([file, spec]) => ({ file, spec }));
+}
+//# sourceMappingURL=sources.js.map

package/dist/sources.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.23.1",
+    "@metaobjectsdev/metadata": "0.24.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/src/agent-docs/body.ts

@@ -222,7 +222,7 @@ export default defineConfig({
 
 Filters live on the generator entry: \`routesFile({ filter: e => e.name !== "AuditLog" })\`
 
-\`.metaobjects/config.json\` is unchanged — it still holds static project state (schema_version, pending_in_git, confidence_thresholds). Generator wiring belongs in \`metaobjects.config.ts\` so TypeScript can type-check the imports.
+\`.metaobjects/config.json\` holds static project state (schema_version, pending_in_git, confidence_thresholds) **and \`sources\` — the set of places your metadata comes from** (see "Where metadata comes from" below). Generator wiring belongs in \`metaobjects.config.ts\` so TypeScript can type-check the imports.
 
 ## Generated hooks + grids (TanStack)
 
@@ -503,13 +503,35 @@ metaobjects/
 └── _pending/<pkg>.json       proposed packages awaiting review
 
 .metaobjects/
-├── config.json               static project state
+├── config.json               static project state + \`sources\`
 ├── migrations/               written by meta migrate
 └── .gen-state/               codegen merge base (gitignored)
 
 metaobjects.config.ts         generator wiring (committed)
 \`\`\`
 
+### Where metadata comes from — the \`sources\` set
+
+**\`metaobjects/\` is the DEFAULT VALUE of \`sources\`, not a requirement.** When \`sources\` is absent or empty in \`.metaobjects/config.json\`, it takes that default — the \`metaobjects/\` directory beside the \`.metaobjects/\` folder holding the config. \`meta init\` scaffolds \`"sources": []\`, so a project that does nothing takes the default.
+
+Do NOT assume that directory exists. A project may declare \`sources\` and put its metadata anywhere — a sibling module, a shared model repository, a single file — and need not have a directory of that name at all:
+
+\`\`\`json
+{
+  "schema_version": 1,
+  "sources": [
+    { "path": "../model/src/main/resources/metadata" },
+    { "path": "metaobjects" }
+  ]
+}
+\`\`\`
+
+\`meta gen\`, \`meta migrate\`, \`meta verify\`, \`meta docs\` and \`meta export\` all read exactly that set, so pointing \`sources\` elsewhere moves every command together. A \`path\` is read **in place and never installed** or copied.
+
+\`sources\` is read by **all four CLI surfaces** — the Node \`meta\` CLI, \`dotnet meta\` (C#), \`metaobjects\` (Python) and \`metaobjects:generate\` (Java and Kotlin, via Maven). Each resolves the same files from the same declaration.
+
+**\`sources\` is a set, not an ordered list** — resolution is order-independent, so declaration order never changes what loads. \`config.json\` also rejects unknown top-level keys, so a misspelled key is an error rather than a silently ignored one.
+
 ## Worked example
 
 \`\`\`json