@nacre.work/core 0.0.0 → 0.2.0

package/dist/db/migrate.js

@@ -3,6 +3,19 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Client } from 'pg';
 const MIGRATIONS_DIR = fileURLToPath(new URL('../migrations/', import.meta.url));
+/**
+ * How long a migration may wait for a lock before giving up. See the call site.
+ *
+ * A migration that needs longer can say so: `SET LOCAL lock_timeout` inside the
+ * file overrides this for the rest of that transaction, and it is the right
+ * place for the exception because the migration is what knows it is unusual.
+ *
+ * `statement_timeout` is deliberately not touched. Some managed platforms set
+ * one globally and a long index build will hit it — but that is the operator's
+ * configuration, the failure rolls back cleanly, and quietly overriding a bound
+ * somebody chose is worse than failing where they can see it.
+ */
+const LOCK_TIMEOUT = '10s';
 /**
  * Migrations in filename order. Numbered prefixes are compared as numbers, so
  * `0010` sorts after `0009` rather than between `0001` and `0002`.
@@ -81,6 +94,30 @@ export async function migrate(connectionString, migrations = loadMigrations()) {
             }
             await client.query('BEGIN');
             try {
+                // Bounded waiting, set inside the transaction so it reverts on its own.
+                //
+                // `ALTER TABLE` takes ACCESS EXCLUSIVE, which conflicts with everything
+                // including a plain SELECT. With no timeout the sequence on a busy
+                // database is: the ALTER waits behind one long-running query, and every
+                // statement arriving afterwards queues behind the ALTER — because a
+                // lock request is not overtaken by weaker ones. One slow reporting
+                // query therefore stops the entire application for as long as it runs,
+                // and the migration that appeared to be "just adding a column" is what
+                // the outage gets blamed on.
+                //
+                // `lock_timeout`, not `statement_timeout`: the two failures are not
+                // alike. Waiting for a lock is a scheduling problem and retrying in a
+                // quieter minute fixes it, so failing fast is free. Doing the work is
+                // not — a backfill or an index build on a large table legitimately
+                // takes longer than any bound worth setting, and killing it halfway
+                // achieves nothing except a rollback. So the wait is capped and the
+                // work is not.
+                //
+                // Ten seconds because it is far longer than any lock this schema takes
+                // when the queue is empty, and far shorter than a deploy timeout — the
+                // migration fails with `55P03 lock_not_available`, which names the
+                // problem, instead of hanging until someone kills it and has to guess.
+                await client.query(`SET LOCAL lock_timeout = '${LOCK_TIMEOUT}'`);
                 await client.query(migration.sql);
                 await client.query('INSERT INTO schema_migrations (name, checksum) VALUES ($1, $2)', [
                     migration.name,
@@ -91,6 +128,18 @@ export async function migrate(connectionString, migrations = loadMigrations()) {
             }
             catch (cause) {
                 await client.query('ROLLBACK');
+                // 55P03 is `lock_not_available`, and it is worth naming: it is the one
+                // failure here that says nothing about the migration. The SQL is fine,
+                // something else was holding the table, and the fix is to look at
+                // pg_stat_activity rather than at the file.
+                if (cause.code === '55P03') {
+                    throw new Error(`migration ${migration.name} gave up waiting for a lock after ${LOCK_TIMEOUT} ` +
+                        'and was rolled back. Something else is holding the table — a long query, an ' +
+                        'idle-in-transaction session, another migration — so this is not a problem with ' +
+                        'the migration itself and re-running it once the holder is gone will work. ' +
+                        'The wait is capped deliberately: an ALTER queued behind one slow query blocks ' +
+                        'every statement that arrives after it, which takes the application down.', { cause });
+                }
                 throw new Error(`migration ${migration.name} failed and was rolled back`, { cause });
             }
         }

package/dist/db/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../db/migrate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../db/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAA;AAE3B,MAAM,cAAc,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,YAAY,GAAG,KAAK,CAAA;AAO1B;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,cAAc;IACzD,IAAI,OAAiB,CAAA;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yEAAyE;QACzE,uEAAuE;QACvE,uDAAuD;QACvD,MAAM,IAAI,KAAK,CACb,8BAA8B,GAAG,wCAAwC;YACvE,8EAA8E,EAChF,EAAE,KAAK,EAAE,CACV,CAAA;IACH,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;IAC5D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,2EAA2E;QAC3E,0DAA0D;QAC1D,MAAM,IAAI,KAAK,CAAC,oBAAoB,GAAG,gEAAgE,CAAC,CAAA;IAC1G,CAAC;IAED,OAAO,UAAU;SACd,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACrF,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAA;AAC1E,CAAC;AAED,MAAM,MAAM,GAAG;;;;;;CAMd,CAAA;AAED,KAAK,UAAU,QAAQ,CAAC,GAAW;IACjC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;IACnF,OAAO,CAAC,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AACzF,CAAC;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,gBAAwB,EACxB,aAAmC,cAAc,EAAE;IAEnD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAA;IAC/C,MAAM,MAAM,CAAC,OAAO,EAAE,CAAA;IAEtB,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,MAAM,OAAO,GAAa,EAAE,CAAA;IAE5B,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QAE1B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,CACjC,8CAA8C,CAC/C,CAAA;QACD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;QAE7D,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;YACzC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;YAE3C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;oBACrB,MAAM,IAAI,KAAK,CACb,aAAa,SAAS,CAAC,IAAI,qCAAqC;wBAC9D,kEAAkE;wBAClE,mEAAmE;wBACnE,6CAA6C,CAChD,CAAA;gBACH,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;gBAC5B,SAAQ;YACV,CAAC;YAED,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;YAC3B,IAAI,CAAC;gBACH,wEAAwE;gBACxE,EAAE;gBACF,wEAAwE;gBACxE,mEAAmE;gBACnE,wEAAwE;gBACxE,oEAAoE;gBACpE,mEAAmE;gBACnE,uEAAuE;gBACvE,uEAAuE;gBACvE,6BAA6B;gBAC7B,EAAE;gBACF,oEAAoE;gBACpE,sEAAsE;gBACtE,sEAAsE;gBACtE,mEAAmE;gBACnE,oEAAoE;gBACpE,oEAAoE;gBACpE,eAAe;gBACf,EAAE;gBACF,uEAAuE;gBACvE,uEAAuE;gBACvE,mEAAmE;gBACnE,uEAAuE;gBACvE,MAAM,MAAM,CAAC,KAAK,CAAC,6BAA6B,YAAY,GAAG,CAAC,CAAA;gBAChE,MAAM,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;gBACjC,MAAM,MAAM,CAAC,KAAK,CAAC,gEAAgE,EAAE;oBACnF,SAAS,CAAC,IAAI;oBACd,GAAG;iBACJ,CAAC,CAAA;gBACF,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;gBAC5B,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;YAC9B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;gBAE9B,uEAAuE;gBACvE,uEAAuE;gBACvE,kEAAkE;gBAClE,4CAA4C;gBAC5C,IAAK,KAA2B,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;oBAClD,MAAM,IAAI,KAAK,CACb,aAAa,SAAS,CAAC,IAAI,qCAAqC,YAAY,GAAG;wBAC7E,8EAA8E;wBAC9E,iFAAiF;wBACjF,4EAA4E;wBAC5E,gFAAgF;wBAChF,0EAA0E,EAC5E,EAAE,KAAK,EAAE,CACV,CAAA;gBACH,CAAC;gBAED,MAAM,IAAI,KAAK,CAAC,aAAa,SAAS,CAAC,IAAI,6BAA6B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;YACtF,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,GAAG,EAAE,CAAA;IACpB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAA;AAC7B,CAAC"}

package/dist/index.d.ts

@@ -1,16 +1,34 @@
 export * from './types.js';
 export * from './authz/index.js';
-export { loadConfig, ConfigError } from './config.js';
+export { parseFilters, parseMetadata, MetadataError, MAX_METADATA_KEYS, MAX_METADATA_KEY_LENGTH, MAX_METADATA_LIST, MAX_METADATA_VALUE_LENGTH, } from './metadata.js';
+export type { Metadata } from './metadata.js';
+export { loadConfig, loadJwtKeys, ConfigError } from './config.js';
+export { protectedResourceMetadata, PROTECTED_RESOURCE_PATH } from './oauth.js';
+export type { ProtectedResourceMetadata } from './oauth.js';
+export type { JwtKeys } from './config.js';
 export type { Config } from './config.js';
-export { createPool, withOrg } from './db/client.js';
+export { acrossOrganizations, createPool, whileAuthenticating, withOrg } from './db/client.js';
 export type { DbOptions, WithOrgOptions } from './db/client.js';
 export { migrate, loadMigrations } from './db/migrate.js';
 export { loadGrants, loadGroupsVersion, loadScopeTree, PostgresGroupGraph } from './authz/store.js';
-export { VectorStore } from './vector/search.js';
+export { explainQdrant, MetadataIndexer, METADATA_INDEX_LIMIT, VectorStore } from './vector/search.js';
+export { MAX_AUDITED_QUERY, queryAudit } from './audit.js';
+export type { QueryAudit } from './audit.js';
+export { configureLogging, createLogger, logger } from './logging.js';
+export type { Logger, LoggerOptions, LogFormat, LogLevel } from './logging.js';
+export { documentKey, S3, S3Error } from './s3.js';
+export type { S3Options } from './s3.js';
 export type { Hit, SearchRequest, VectorStoreOptions } from './vector/search.js';
 export { buildHybridQuery, collectionConfig, collectionName, PAYLOAD_INDEXES, vectorName } from './vector/query.js';
 export type { Branch, HybridQuery } from './vector/query.js';
 export { Counter, Gauge, Histogram, Registry, createMetrics } from './metrics.js';
 export type { Labels, Metrics } from './metrics.js';
 export { collectDatabaseGauges } from './observability.js';
+export { Redis, RedisError } from './redis.js';
+export type { RedisOptions } from './redis.js';
+export { reindexProgress, toStateJson, fromStateJson } from './reindex.js';
+export type { ReindexState } from './reindex.js';
+export { hashingLoad, hashPassword, needsRehash, spendVerificationTime, TooBusy, verifyPassword, } from './passwords.js';
+export { installGuards, onListenError } from './lifecycle.js';
+export type { Guards } from './lifecycle.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACrD,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AACpD,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACnG,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAChF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnH,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjF,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAClE,OAAO,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAC/E,YAAY,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAC3D,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAC9F,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACnG,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACtG,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC1D,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC9E,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAClD,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAChF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnH,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjF,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC1E,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,OAAO,EACP,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC7D,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -1,11 +1,20 @@
 export * from './types.js';
 export * from './authz/index.js';
-export { loadConfig, ConfigError } from './config.js';
-export { createPool, withOrg } from './db/client.js';
+export { parseFilters, parseMetadata, MetadataError, MAX_METADATA_KEYS, MAX_METADATA_KEY_LENGTH, MAX_METADATA_LIST, MAX_METADATA_VALUE_LENGTH, } from './metadata.js';
+export { loadConfig, loadJwtKeys, ConfigError } from './config.js';
+export { protectedResourceMetadata, PROTECTED_RESOURCE_PATH } from './oauth.js';
+export { acrossOrganizations, createPool, whileAuthenticating, withOrg } from './db/client.js';
 export { migrate, loadMigrations } from './db/migrate.js';
 export { loadGrants, loadGroupsVersion, loadScopeTree, PostgresGroupGraph } from './authz/store.js';
-export { VectorStore } from './vector/search.js';
+export { explainQdrant, MetadataIndexer, METADATA_INDEX_LIMIT, VectorStore } from './vector/search.js';
+export { MAX_AUDITED_QUERY, queryAudit } from './audit.js';
+export { configureLogging, createLogger, logger } from './logging.js';
+export { documentKey, S3, S3Error } from './s3.js';
 export { buildHybridQuery, collectionConfig, collectionName, PAYLOAD_INDEXES, vectorName } from './vector/query.js';
 export { Counter, Gauge, Histogram, Registry, createMetrics } from './metrics.js';
 export { collectDatabaseGauges } from './observability.js';
+export { Redis, RedisError } from './redis.js';
+export { reindexProgress, toStateJson, fromStateJson } from './reindex.js';
+export { hashingLoad, hashPassword, needsRehash, spendVerificationTime, TooBusy, verifyPassword, } from './passwords.js';
+export { installGuards, onListenError } from './lifecycle.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAErD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAEpD,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACnG,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAClE,OAAO,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAI/E,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAE9F,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACnG,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACtG,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE1D,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAErE,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAGlD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE9C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE1E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,OAAO,EACP,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,57 @@
+/**
+ * What every process does when it is asked to stop, and when it is about to
+ * die for a reason nobody wrote down.
+ *
+ * Three processes ship here — api, mcp, worker — and none of them had any of
+ * this. The consequences were all of the same shape: a failure that produced no
+ * log line, so the operator saw a container restart and had nothing to read.
+ *
+ * - **No `unhandledRejection` handler.** Node terminates the process on one,
+ *   with a raw stack on stderr and no service name, no timestamp in the format
+ *   every other line uses, and nothing to join to a request.
+ * - **No `error` listener on `listen`.** `EADDRINUSE` is emitted on the server
+ *   *after* `main()` has already resolved, so `main().catch` never sees it and
+ *   the careful ConfigError path — which exits 2 with an explanation — is
+ *   bypassed by the one startup failure an operator hits most.
+ * - **No deadline on shutdown.** `server.close()` waits for in-flight requests
+ *   with no upper bound. One request blocked on a slow dependency means the
+ *   callback never runs, the pool is never released, and the orchestrator
+ *   SIGKILLs at the end of its grace period — turning every rolling deploy into
+ *   an abrupt one, silently.
+ */
+export interface Guards {
+    /** Named in every line, so two processes in one log stream are tellable apart. */
+    readonly service: string;
+    /**
+     * Release what the process holds. Called once, with a deadline.
+     *
+     * Whatever it does, it must not be the only thing standing between the
+     * process and exiting: if it hangs, the deadline below exits anyway.
+     */
+    readonly shutdown?: () => Promise<void> | void;
+    /** How long `shutdown` gets. Shorter than any orchestrator's grace period. */
+    readonly graceMs?: number;
+    /** Injected in tests. Nothing else should be replacing this. */
+    readonly exit?: (code: number) => void;
+}
+/**
+ * Install the handlers. Returns a `stop` to call from a signal handler.
+ *
+ * Idempotent: a second SIGTERM while shutting down is ignored rather than
+ * starting a second shutdown, because an orchestrator that sends one and then
+ * loses patience sends another.
+ */
+export declare function installGuards(guards: Guards): {
+    stop: (signal: string) => void;
+};
+/**
+ * Fail a `listen` the way every other startup failure fails.
+ *
+ * `server.listen(port, cb)` reports a bound port through the callback and a
+ * refusal through an `error` event — which arrives after `main()` has resolved,
+ * so nothing was catching it.
+ */
+export declare function onListenError(server: {
+    on(event: 'error', listener: (error: NodeJS.ErrnoException) => void): unknown;
+}, service: string, port: number, exit?: (code: number) => void): void;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../lifecycle.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,MAAM;IACrB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC9C,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACvC;AAkBD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,CAmDhF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,KAAK,IAAI,GAAG,OAAO,CAAA;CAAE,EACzF,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAmC,GAC1D,IAAI,CAWN"}

package/dist/lifecycle.js

@@ -0,0 +1,84 @@
+import { logger } from './logging.js';
+/**
+ * Through the process logger, so `NACRE_LOG_FORMAT` reaches these too.
+ *
+ * The level is a parameter rather than always `error`: a clean shutdown is not
+ * a failure, and reporting it as one is how a dashboard counting errors turns
+ * every deploy into an incident. What is an error stays an error.
+ */
+const log = (level, service, msg, extra = {}) => {
+    logger[level](msg, { service, ...extra });
+};
+/**
+ * Install the handlers. Returns a `stop` to call from a signal handler.
+ *
+ * Idempotent: a second SIGTERM while shutting down is ignored rather than
+ * starting a second shutdown, because an orchestrator that sends one and then
+ * loses patience sends another.
+ */
+export function installGuards(guards) {
+    const { service, shutdown, graceMs = 10_000, exit = (code) => process.exit(code) } = guards;
+    let stopping = false;
+    process.on('unhandledRejection', (reason) => {
+        // Logged and then rethrown by exiting, rather than swallowed. A promise
+        // nobody awaited failing means the process is in a state its author did not
+        // plan for, and continuing from there is how one bad request becomes a
+        // corrupt one.
+        log('error', service, 'unhandled rejection; exiting', { error: String(reason).slice(0, 500) });
+        exit(1);
+    });
+    process.on('uncaughtException', (error) => {
+        log('error', service, 'uncaught exception; exiting', {
+            error: String(error).slice(0, 500),
+            stack: error.stack?.split('\n').slice(1, 6).join(' | '),
+        });
+        exit(1);
+    });
+    const stop = (signal) => {
+        if (stopping)
+            return;
+        stopping = true;
+        log('info', service, 'shutting down', { signal });
+        // The deadline runs whatever happens, and `unref` keeps it from being the
+        // thing that holds the process open once everything else has let go.
+        const deadline = setTimeout(() => {
+            log('error', service, 'shutdown did not finish in time; exiting anyway', { grace_ms: graceMs });
+            exit(1);
+        }, graceMs);
+        deadline.unref();
+        void (async () => {
+            try {
+                await shutdown?.();
+                clearTimeout(deadline);
+                exit(0);
+            }
+            catch (error) {
+                log('error', service, 'shutdown failed', { error: String(error).slice(0, 500) });
+                clearTimeout(deadline);
+                exit(1);
+            }
+        })();
+    };
+    process.on('SIGTERM', () => stop('SIGTERM'));
+    process.on('SIGINT', () => stop('SIGINT'));
+    return { stop };
+}
+/**
+ * Fail a `listen` the way every other startup failure fails.
+ *
+ * `server.listen(port, cb)` reports a bound port through the callback and a
+ * refusal through an `error` event — which arrives after `main()` has resolved,
+ * so nothing was catching it.
+ */
+export function onListenError(server, service, port, exit = (code) => process.exit(code)) {
+    server.on('error', (error) => {
+        const detail = error.code === 'EADDRINUSE'
+            ? `port ${port} is already in use`
+            : error.code === 'EACCES'
+                ? `port ${port} needs privileges this process does not have`
+                : String(error);
+        log('error', service, 'could not listen', { port, detail });
+        exit(2);
+    });
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

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

package/dist/logging.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Logging, at the level and in the format the deployment asked for.
+ *
+ * `NACRE_LOG_LEVEL` and `NACRE_LOG_FORMAT` were validated at startup and read
+ * by nothing: every process wrote structured JSON at one level, so an operator
+ * setting `warn` still got every `info` line and one setting `text` still got
+ * JSON. Both are among the first variables anyone sets.
+ *
+ * ─── what does not go through here ───
+ *
+ * **Configuration errors.** They happen before a configuration exists, so there
+ * is nothing to ask about the level, and a process that cannot start must say
+ * why whatever anyone configured. Those stay on `console.error`.
+ *
+ * **`init` and `migrate` output.** Those are commands a person runs and reads —
+ * the printed org id, the applied migrations. That is program output, like
+ * `--help`, and putting it behind a level would mean `NACRE_LOG_LEVEL=warn`
+ * silently swallows the one line the command exists to produce.
+ *
+ * ─── what a field may hold ───
+ *
+ * The same rule as everywhere else in this repository: no document contents and
+ * no full query text. This module cannot enforce that — it takes what it is
+ * given — so it is stated where the fields are named rather than here.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type LogFormat = 'json' | 'text';
+export interface Logger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+export interface LoggerOptions {
+    readonly level: LogLevel;
+    readonly format: LogFormat;
+    /** Injected so a test can assert on a line rather than on a moving timestamp. */
+    readonly now?: () => Date;
+    /** Injected for the same reason. Defaults to the console. */
+    readonly write?: (level: LogLevel, line: string) => void;
+}
+export declare function createLogger(options: LoggerOptions): Logger;
+export declare function configureLogging(options: LoggerOptions): void;
+/** Delegates on every call, so a module may hold this and still see the change. */
+export declare const logger: Logger;
+//# sourceMappingURL=logging.d.ts.map

package/dist/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../logging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAC1D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAA;AAIvC,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC/D;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACzD;AA+BD,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CA6B3D;AAiBD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAE7D;AAED,mFAAmF;AACnF,eAAO,MAAM,MAAM,EAAE,MAKpB,CAAA"}

package/dist/logging.js

@@ -0,0 +1,110 @@
+/**
+ * Logging, at the level and in the format the deployment asked for.
+ *
+ * `NACRE_LOG_LEVEL` and `NACRE_LOG_FORMAT` were validated at startup and read
+ * by nothing: every process wrote structured JSON at one level, so an operator
+ * setting `warn` still got every `info` line and one setting `text` still got
+ * JSON. Both are among the first variables anyone sets.
+ *
+ * ─── what does not go through here ───
+ *
+ * **Configuration errors.** They happen before a configuration exists, so there
+ * is nothing to ask about the level, and a process that cannot start must say
+ * why whatever anyone configured. Those stay on `console.error`.
+ *
+ * **`init` and `migrate` output.** Those are commands a person runs and reads —
+ * the printed org id, the applied migrations. That is program output, like
+ * `--help`, and putting it behind a level would mean `NACRE_LOG_LEVEL=warn`
+ * silently swallows the one line the command exists to produce.
+ *
+ * ─── what a field may hold ───
+ *
+ * The same rule as everywhere else in this repository: no document contents and
+ * no full query text. This module cannot enforce that — it takes what it is
+ * given — so it is stated where the fields are named rather than here.
+ */
+const ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+/**
+ * `warn` and `error` to stderr, the rest to stdout.
+ *
+ * Not a style choice: a container that pipes stdout into a log shipper and
+ * leaves stderr on the terminal is a real deployment, and a failure that went
+ * to stdout with everything else is a failure nobody saw at 3am.
+ */
+function toConsole(level, line) {
+    if (level === 'warn')
+        console.warn(line);
+    else if (level === 'error')
+        console.error(line);
+    else
+        console.log(line);
+}
+/**
+ * `key=value`, with anything ambiguous quoted.
+ *
+ * Text format is for a person reading a terminal, so it is optimised for
+ * scanning rather than for parsing — but a value containing a space or a quote
+ * still has to survive, or two fields read as one.
+ */
+function render(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string') {
+        return /[\s"=]/.test(value) ? JSON.stringify(value) : value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return JSON.stringify(value);
+}
+export function createLogger(options) {
+    const threshold = ORDER[options.level];
+    const now = options.now ?? (() => new Date());
+    const write = options.write ?? toConsole;
+    const emit = (level, message, fields) => {
+        if (ORDER[level] < threshold)
+            return;
+        const ts = now().toISOString();
+        if (options.format === 'json') {
+            // `msg` first and named the same as before, because every existing line
+            // was `{"msg": ...}` and anything already grepping for it should keep
+            // working. The level and timestamp are additions, not a replacement.
+            write(level, JSON.stringify({ level, ts, msg: message, ...fields }));
+            return;
+        }
+        const rest = Object.entries(fields ?? {})
+            .map(([key, value]) => ` ${key}=${render(value)}`)
+            .join('');
+        write(level, `${ts} ${level.toUpperCase().padEnd(5)} ${message}${rest}`);
+    };
+    return {
+        debug: (m, f) => emit('debug', m, f),
+        info: (m, f) => emit('info', m, f),
+        warn: (m, f) => emit('warn', m, f),
+        error: (m, f) => emit('error', m, f),
+    };
+}
+/**
+ * The process-wide logger.
+ *
+ * A module-level default that `configureLogging` replaces once the
+ * configuration is read. Deliberately the one piece of global state in this
+ * repository, and it is safe to be: it carries no authorization semantics, the
+ * worst a wrong one does is print at the wrong level, and the alternative —
+ * threading a logger through every adapter and port — buys nothing a reader of
+ * those signatures would want.
+ *
+ * The default is `info`/`json`, so a module that logs before `configureLogging`
+ * runs behaves exactly as the whole system did before this existed.
+ */
+let current = createLogger({ level: 'info', format: 'json' });
+export function configureLogging(options) {
+    current = createLogger(options);
+}
+/** Delegates on every call, so a module may hold this and still see the change. */
+export const logger = {
+    debug: (m, f) => current.debug(m, f),
+    info: (m, f) => current.info(m, f),
+    warn: (m, f) => current.warn(m, f),
+    error: (m, f) => current.error(m, f),
+};
+//# sourceMappingURL=logging.js.map

package/dist/logging.js.map

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

package/dist/metadata.d.ts

@@ -0,0 +1,50 @@
+import type { MetadataValue } from './authz/filter.js';
+/**
+ * Document metadata: what a caller may write, and what they may narrow a search
+ * by.
+ *
+ * One module for both ends on purpose. Ingest and search accept the same shape
+ * from the same untrusted place, and two validators would drift — the ingest
+ * side would grow a type the search side could not express, or the search side
+ * would accept a key ingest had refused, and a caller would be filtering on a
+ * field that can never exist.
+ *
+ * Everything here is a bound. Metadata is written into the vector payload of
+ * *every chunk of a document*, so a key is stored once per point and a
+ * thousand-chunk document multiplies whatever arrives here by a thousand. The
+ * limits are deliberately small; a knowledge index wants `source`, `team`,
+ * `updated_at`, not a document's worth of JSON a second time.
+ */
+/** Keys per document. */
+export declare const MAX_METADATA_KEYS = 32;
+export declare const MAX_METADATA_KEY_LENGTH = 64;
+/** A string value, and every string inside a list value. */
+export declare const MAX_METADATA_VALUE_LENGTH = 256;
+/** Values in one list. */
+export declare const MAX_METADATA_LIST = 32;
+export type Metadata = Readonly<Record<string, MetadataValue>>;
+export declare class MetadataError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate and normalise metadata arriving from a request.
+ *
+ * Raises rather than dropping what it does not like. A silently discarded key
+ * is a document a caller believes is tagged and a filter that will never match
+ * it — the same class of failure as a search parameter read by nothing, and the
+ * reason `filters` answered 400 rather than being ignored.
+ */
+export declare function parseMetadata(raw: unknown, what?: string): Metadata;
+/**
+ * The same bounds, plus the one rule that belongs only to filtering.
+ *
+ * An empty list is a legitimate *value* — a document may be tagged with no
+ * teams — and an impossible *restriction*: "team is one of nothing" matches
+ * nothing at all. `buildFilter` refuses to encode it, deliberately, so that
+ * what an impossible restriction means stays the caller's decision rather than
+ * the query builder's. This is where that decision is made for a request: a 400
+ * naming the key, because a client that built a list and put nothing in it has
+ * a bug, and answering with an empty result would hide it.
+ */
+export declare function parseFilters(raw: unknown): Metadata;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEtD;;;;;;;;;;;;;;;GAeG;AAEH,yBAAyB;AACzB,eAAO,MAAM,iBAAiB,KAAK,CAAA;AACnC,eAAO,MAAM,uBAAuB,KAAK,CAAA;AACzC,4DAA4D;AAC5D,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAC5C,0BAA0B;AAC1B,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAanC,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAA;AAE9D,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AA6BD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,SAAa,GAAG,QAAQ,CAsCvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAWnD"}