@fulmenhq/tsfulmen 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -9,6 +9,88 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.1.8] - 2025-11-08
+
+**Remote Sync Infrastructure** - Upgraded to goneat v0.3.4 with force-remote configuration and improved build artifact testing.
+
+### Fixed
+
+- **Verification Script TypeScript Errors**:
+  - Fixed incorrect default import for `tmpdir` from `node:os`
+  - Corrected `run()` function return type to handle `Buffer | string`
+  - Added `'ignore'` to stdio type union
+  - Removed unused `existsSync` import
+- **Missing await on async catalog functions**: Added proper `await` to `getSignalsVersion()` call in verification script
+- **Build Artifacts Test Failure**: Fixed test expecting built `dist/` artifacts by ensuring build runs before tests
+
+### Added
+
+- **Unit Tests for Verification Script**: Created `scripts/__tests__/verify-published-package.test.ts` with 5 tests
+  - Validates TypeScript compilation
+  - Checks async/await usage for all catalog functions
+  - Verifies VERSION export validation logic
+  - Ensures proper cleanup in finally block
+  - Validates stdio options correctness
+- **Remote-Only Sync Configuration**: Updated `.goneat/ssot-consumer.yaml` with new `force_remote: true` field
+  - Replaces deprecated `method: remote` with standardized `force_remote: true`
+  - Ensures CI/CD and fresh clones always use remote Crucible v0.2.8
+  - Prevents accidental local sync from `../crucible` directories
+
+### Changed
+
+- **Goneat Upgrade**: Updated from v0.3.3 to v0.3.4 with new force-remote capabilities
+- **SSOT Configuration**: Migrated to new goneat v0.3.4 schema with `force_remote` field support
+- **Makefile Sync Target**: Uses `--force-remote` flag to override any local auto-detection
+- **Provenance Tracking**: Enhanced provenance metadata shows `forced_remote: true` and `forced_by: flag`
+
+### Meta
+
+- Addresses the "chicken and egg" problem: verification tooling now has its own verification tests
+- Ensures code quality checks are not dismissed - all TypeScript errors resolved
+- Guarantees reproducible remote syncs for all users regardless of local directory structure
+
+---
+
+## [0.1.7] - 2025-11-06
+
+**Release Infrastructure** - Automated version consistency checks and workflow improvements to prevent version drift.
+
+### Fixed
+
+- **VERSION Constant Drift**: VERSION exported from code now automatically synchronized with package.json
+  - Enhanced `scripts/version-sync.ts` to update `src/index.ts` VERSION constant
+  - Added VERSION consistency verification to `scripts/verify-package-artifacts.ts`
+  - Prevents mismatch between package.json version and runtime VERSION export (issue found in v0.1.6)
+
+### Changed
+
+- **Makefile Improvements**:
+  - Updated `prepush` target to run `fmt` before `check-all`
+  - Ensures formatting is applied before quality checks
+- **Bootstrap Process**: Verified `./bin/goneat` installation via tools.yaml download method works correctly
+
+### Infrastructure
+
+- Pre-publish artifact verification now validates VERSION consistency
+- Automated version synchronization across package.json and source code
+- Improved release workflow to catch version drift issues early
+
+**Note**: v0.1.6 was published to npm but had VERSION constant mismatch (package.json: 0.1.6, exported: 0.1.5). GitHub release v0.1.6 was removed. This release fixes that infrastructure gap.
+
+---
+
+## [0.1.6] - 2025-11-06
+
+**Skipped** - Published to npm but not released on GitHub due to VERSION constant mismatch discovered post-publish. See v0.1.7 for details and fixes.
+
+### Issues
+
+- VERSION constant exported `'0.1.5'` while package.json declared `0.1.6`
+- GitHub release removed; npm package remains but is not recommended
+- Users should upgrade to v0.1.7 or later
+
+---
+
 ## [0.1.5] - 2025-11-05
 
 **Application Identity Module** - Complete implementation of Crucible app-identity standard v1.0.0 with discovery, caching, validation, and CLI tooling.

package/config/crucible-ts/library/foundry/exit-codes.snapshot.json

@@ -283,22 +283,22 @@
     "129": {
       "name": "EXIT_SIGNAL_HUP",
       "category": "signals",
-      "description": "Hangup signal (SIGHUP)",
-      "context": "Terminal disconnected, config reload requested",
+      "description": "Hangup signal (SIGHUP) - config reload via restart",
+      "context": "Config reload via restart-based pattern (mandatory schema validation).\nProcess exits with 129, supervisor restarts with new config.\nSee signals.yaml for reload behavior definition.",
       "bsd_equivalent": "128 + 1"
     },
     "130": {
       "name": "EXIT_SIGNAL_INT",
       "category": "signals",
-      "description": "Interrupt signal (SIGINT)",
-      "context": "Ctrl+C pressed, user interrupt",
+      "description": "Interrupt signal (SIGINT) - user interrupt with Ctrl+C double-tap",
+      "context": "Ctrl+C pressed. First tap initiates graceful shutdown, second within 2s forces immediate exit.\nSame exit code (130) for both graceful and force modes.\nSee signals.yaml for double-tap behavior definition.",
       "bsd_equivalent": "128 + 2"
     },
     "131": {
       "name": "EXIT_SIGNAL_QUIT",
       "category": "signals",
-      "description": "Quit signal (SIGQUIT)",
-      "context": "Ctrl+\\ pressed, core dump requested",
+      "description": "Quit signal (SIGQUIT) - immediate exit",
+      "context": "Ctrl+\\ on Unix, Ctrl+Break on Windows. Immediate termination without cleanup.\nUse for emergency shutdown or debugging (core dumps).",
       "bsd_equivalent": "128 + 3"
     },
     "137": {
@@ -309,43 +309,41 @@
       "bsd_equivalent": "128 + 9",
       "python_note": "Cannot be caught in Python (OS-level)"
     },
+    "138": {
+      "name": "EXIT_SIGNAL_USR1",
+      "category": "signals",
+      "description": "User-defined signal 1 (SIGUSR1) - custom handler",
+      "context": "Application-specific signal (e.g., reopen logs, dump stats, trigger profiling).\nApplications register custom handlers. Exit code 138 on Linux (128+10).\nPlatform differences: macOS/FreeBSD use signal 30 (exit 158), not 10."
+    },
+    "140": {
+      "name": "EXIT_SIGNAL_USR2",
+      "category": "signals",
+      "description": "User-defined signal 2 (SIGUSR2) - custom handler",
+      "context": "Application-specific signal (e.g., toggle debug mode, rotate credentials).\nApplications register custom handlers. Exit code 140 on Linux (128+12).\nPlatform differences: macOS/FreeBSD use signal 31 (exit 159), not 12."
+    },
     "141": {
       "name": "EXIT_SIGNAL_PIPE",
       "category": "signals",
-      "description": "Broken pipe (SIGPIPE)",
-      "context": "Writing to closed pipe/socket, reader terminated",
+      "description": "Broken pipe (SIGPIPE) - observe only",
+      "context": "Writing to closed pipe/socket. Fulmen default is observe_only (log + graceful exit).\nApplications may override to ignore for network services.\nSee signals.yaml for SIGPIPE handling guidance.",
       "bsd_equivalent": "128 + 13",
       "python_note": "Raised as BrokenPipeError exception"
     },
     "142": {
       "name": "EXIT_SIGNAL_ALRM",
       "category": "signals",
-      "description": "Alarm signal (SIGALRM)",
-      "context": "Timer expiration, alarm clock",
+      "description": "Alarm signal (SIGALRM) - watchdog timeout",
+      "context": "Watchdog timer expired. Treat as timeout-induced exit.\nWatchdog pattern out of scope for v1.0.0 module implementations.",
       "bsd_equivalent": "128 + 14",
       "python_note": "Supported by signal module, rarely used in practice"
     },
     "143": {
       "name": "EXIT_SIGNAL_TERM",
       "category": "signals",
-      "description": "Termination signal (SIGTERM)",
-      "context": "Graceful shutdown requested, normal termination",
+      "description": "Termination signal (SIGTERM) - graceful shutdown",
+      "context": "Graceful shutdown requested by container orchestrator or process supervisor.\nStandard 30-second timeout for cleanup. Applications run cleanup handlers before exit.\nSee signals.yaml for graceful shutdown behavior definition.",
       "bsd_equivalent": "128 + 15",
       "python_note": "Default signal for graceful shutdown"
-    },
-    "159": {
-      "name": "EXIT_SIGNAL_USR1",
-      "category": "signals",
-      "description": "User-defined signal 1 (SIGUSR1)",
-      "context": "Application-specific signal handling (e.g., reopen logs, dump stats)",
-      "bsd_equivalent": "128 + 31"
-    },
-    "160": {
-      "name": "EXIT_SIGNAL_USR2",
-      "category": "signals",
-      "description": "User-defined signal 2 (SIGUSR2)",
-      "context": "Application-specific signal handling (e.g., toggle debug mode)",
-      "bsd_equivalent": "128 + 32"
     }
   }
 }

package/config/crucible-ts/library/foundry/simplified-modes.snapshot.json

@@ -48,7 +48,16 @@
         93,
         94,
         95,
-        96
+        96,
+        129,
+        130,
+        131,
+        137,
+        138,
+        140,
+        141,
+        142,
+        143
       ],
       "2": [
         64
@@ -92,7 +101,16 @@
         51,
         52,
         53,
-        54
+        54,
+        129,
+        130,
+        131,
+        137,
+        138,
+        140,
+        141,
+        142,
+        143
       ],
       "5": [
         70,
@@ -103,14 +121,17 @@
       "6": [
         91,
         92,
+        93,
         94,
-        95
+        95,
+        96
       ],
       "7": [
         80,
         81,
         82,
-        83
+        83,
+        84
       ]
     }
   }

package/config/crucible-ts/taxonomy/metrics.yaml

@@ -18,6 +18,32 @@ $defs:
       - logging_emit_count
       - logging_emit_latency_ms
       - goneat_command_duration_ms
+      - prometheus_exporter_refresh_duration_seconds
+      - prometheus_exporter_refresh_total
+      - prometheus_exporter_refresh_errors_total
+      - prometheus_exporter_refresh_inflight
+      - prometheus_exporter_http_requests_total
+      - prometheus_exporter_http_errors_total
+      - prometheus_exporter_restarts_total
+      - foundry_mime_detections_total_json
+      - foundry_mime_detections_total_xml
+      - foundry_mime_detections_total_yaml
+      - foundry_mime_detections_total_csv
+      - foundry_mime_detections_total_plain_text
+      - foundry_mime_detections_total_unknown
+      - foundry_mime_detection_ms_json
+      - foundry_mime_detection_ms_xml
+      - foundry_mime_detection_ms_yaml
+      - foundry_mime_detection_ms_csv
+      - foundry_mime_detection_ms_plain_text
+      - foundry_mime_detection_ms_unknown
+      - error_handling_wraps_total
+      - error_handling_wrap_ms
+      - fulhash_operations_total_xxh3_128
+      - fulhash_operations_total_sha256
+      - fulhash_hash_string_total
+      - fulhash_bytes_hashed_total
+      - fulhash_operation_ms
   metricUnit:
     type: string
     enum:
@@ -25,11 +51,12 @@ $defs:
       - ms
       - bytes
       - percent
+      - s
 properties:
   version:
     type: string
-    description: Taxonomy version (CalVer).
-    pattern: "^\\d{4}\\.\\d{2}\\.\\d+$"
+    description: Taxonomy version (SemVer, aligned with Crucible releases).
+    pattern: "^\\d+\\.\\d+\\.\\d+$"
   defaults:
     type: object
     description: Default configuration applied across metrics.
@@ -66,7 +93,7 @@ required:
   - version
   - metrics
 additionalProperties: false
-version: "2025.10.3"
+version: "0.2.8"
 defaults:
   histogram_buckets:
     ms_metrics:
@@ -113,3 +140,132 @@ metrics:
   - name: goneat_command_duration_ms
     unit: ms
     description: Duration of goneat command execution (instrumentation helper).
+  - name: prometheus_exporter_refresh_duration_seconds
+    unit: s
+    description: >
+      Time to refresh/export registry data into Prometheus collectors. Uses ADR-0007 buckets converted to seconds: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0]. Required labels: phase (collect|convert|export), result (success|error). Optional labels: error_type.
+
+  - name: prometheus_exporter_refresh_total
+    unit: count
+    description: >
+      Total refresh cycles attempted. Use with result label for success/error breakdown. Exporters SHOULD emit both this and prometheus_exporter_refresh_errors_total. Required labels: result (success|error). Optional labels: error_type.
+
+  - name: prometheus_exporter_refresh_errors_total
+    unit: count
+    description: >
+      Failed refresh cycles with detailed error classification. Sum MUST equal prometheus_exporter_refresh_total{result="error"}. Required labels: error_type (validation|io|timeout|other). Optional labels: phase.
+
+  - name: prometheus_exporter_refresh_inflight
+    unit: count
+    description: >
+      Number of concurrent refresh operations currently running. Optional labels: phase.
+
+  - name: prometheus_exporter_http_requests_total
+    unit: count
+    description: >
+      HTTP scrape/exposition requests handled by exporter. Distinct from prom-client defaults; recommend disabling client defaults when using this. Required labels: status (HTTP code), path. Optional labels: client (high cardinality warning).
+
+  - name: prometheus_exporter_http_errors_total
+    unit: count
+    description: >
+      HTTP exposition failures (5xx, auth failures, timeouts). Required labels: status (HTTP code), path. Optional labels: client (high cardinality warning).
+
+  - name: prometheus_exporter_restarts_total
+    unit: count
+    description: >
+      Exporter refresh loop or HTTP server restarts. Required labels: reason (config_change|error|manual|other).
+
+  - name: foundry_mime_detections_total_json
+    unit: count
+    description: >
+      Total JSON MIME type detections performed by the Foundry module. Tracks usage patterns for JSON content processing.
+
+  - name: foundry_mime_detections_total_xml
+    unit: count
+    description: >
+      Total XML MIME type detections performed by the Foundry module. Tracks usage patterns for XML content processing.
+
+  - name: foundry_mime_detections_total_yaml
+    unit: count
+    description: >
+      Total YAML MIME type detections performed by the Foundry module. Tracks usage patterns for YAML content processing.
+
+  - name: foundry_mime_detections_total_csv
+    unit: count
+    description: >
+      Total CSV MIME type detections performed by the Foundry module. Tracks usage patterns for CSV content processing.
+
+  - name: foundry_mime_detections_total_plain_text
+    unit: count
+    description: >
+      Total plain text MIME type detections performed by the Foundry module. Tracks usage patterns for plain text content processing.
+
+  - name: foundry_mime_detections_total_unknown
+    unit: count
+    description: >
+      Total unknown/binary MIME type detections performed by the Foundry module. Tracks usage patterns for unknown content types.
+
+  - name: foundry_mime_detection_ms_json
+    unit: ms
+    description: >
+      JSON MIME type detection latency in milliseconds. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables performance analysis for JSON detection algorithms.
+
+  - name: foundry_mime_detection_ms_xml
+    unit: ms
+    description: >
+      XML MIME type detection latency in milliseconds. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables performance analysis for XML detection algorithms.
+
+  - name: foundry_mime_detection_ms_yaml
+    unit: ms
+    description: >
+      YAML MIME type detection latency in milliseconds. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables performance analysis for YAML detection algorithms.
+
+  - name: foundry_mime_detection_ms_csv
+    unit: ms
+    description: >
+      CSV MIME type detection latency in milliseconds. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables performance analysis for CSV detection algorithms.
+
+  - name: foundry_mime_detection_ms_plain_text
+    unit: ms
+    description: >
+      Plain text MIME type detection latency in milliseconds. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables performance analysis for plain text detection algorithms.
+
+  - name: foundry_mime_detection_ms_unknown
+    unit: ms
+    description: >
+      Unknown/binary MIME type detection latency in milliseconds. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables performance analysis for fallback detection logic.
+
+  - name: error_handling_wraps_total
+    unit: count
+    description: >
+      Total error wrap operations performed by the Error Handling module. Tracks error handling patterns and frequency across the application.
+
+  - name: error_handling_wrap_ms
+    unit: ms
+    description: >
+      Error wrap operation latency in milliseconds. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables detection of error handling performance regressions.
+
+  - name: fulhash_operations_total_xxh3_128
+    unit: count
+    description: >
+      Total XXH3-128 hash operations performed by the FulHash module. Tracks usage of the fast, non-cryptographic hash algorithm for performance-oriented scenarios.
+
+  - name: fulhash_operations_total_sha256
+    unit: count
+    description: >
+      Total SHA256 hash operations performed by the FulHash module. Tracks usage of the cryptographic hash algorithm for security-oriented scenarios.
+
+  - name: fulhash_hash_string_total
+    unit: count
+    description: >
+      Total string hash operations performed by the FulHash module (any algorithm). Tracks the common use case of hashing string data.
+
+  - name: fulhash_bytes_hashed_total
+    unit: bytes
+    description: >
+      Total bytes processed across all hash operations by the FulHash module. Counter value represents cumulative byte count. Enables capacity planning and throughput analysis.
+
+  - name: fulhash_operation_ms
+    unit: ms
+    description: >
+      Hash operation latency in milliseconds for all algorithms. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables performance benchmarking across XXH3-128 and SHA256.

package/config/crucible-ts/taxonomy/repository-categories.yaml

@@ -19,7 +19,10 @@ categories:
     typicalConsumers:
       - "Operations automation"
       - "MCP servers"
-    notes: "Requires request correlation IDs and Prometheus metrics"
+    notes: "Requires request correlation IDs and Prometheus metrics. Templates (forge-workhorse-*) must comply with CDRL standard."
+    references:
+      - "docs/architecture/fulmen-forge-workhorse-standard.md"
+      - "docs/architecture/fulmen-template-cdrl-standard.md"
   - key: service
     summary: "Long-running HTTP/gRPC services without interactive CLI UX"
     primaryEntryPoints:
@@ -54,7 +57,10 @@ categories:
     typicalConsumers:
       - "Fulmen developers"
       - "External stakeholders"
-    notes: "Generated assets must trace back to committed source"
+    notes: "Generated assets must trace back to committed source. Templates (forge-codex-*) must comply with CDRL standard."
+    references:
+      - "docs/architecture/fulmen-forge-codex-standard.md"
+      - "docs/architecture/fulmen-template-cdrl-standard.md"
   - key: sdk
     summary: "Client SDKs targeting external services or APIs"
     primaryEntryPoints:
@@ -64,3 +70,46 @@ categories:
       - "External developers"
       - "Partner integrations"
     notes: "Ship compatibility matrix and error taxonomy"
+  - key: forge-workhorse
+    summary: "Production-ready templates for backend services (Clone → Degit → Refit → Launch)"
+    primaryEntryPoints:
+      - "Template repository (GitHub)"
+      - "CDRL workflow (Clone → Degit → Refit → Launch)"
+      - "make validate-app-identity"
+      - "make doctor"
+    typicalConsumers:
+      - "Developers building new services"
+      - "Teams standardizing on Fulmen stack"
+    notes: "MUST comply with CDRL standard. Named with horse breeds (groningen, percheron). REQUIRED: .fulmen/app.yaml, CDRL validation targets, fulmen_cdrl_guide.md"
+    references:
+      - "docs/architecture/fulmen-forge-workhorse-standard.md"
+      - "docs/architecture/fulmen-template-cdrl-standard.md"
+      - "docs/standards/cdrl/workflow-guide.md"
+      - "docs/standards/makefile-standard.md#annex-b-template-repository-cdrl-targets"
+  - key: forge-codex
+    summary: "Production-ready templates for documentation sites (Clone → Degit → Refit → Launch)"
+    primaryEntryPoints:
+      - "Template repository (GitHub)"
+      - "CDRL workflow (Clone → Degit → Refit → Launch)"
+      - "make validate-app-identity"
+      - "make doctor"
+    typicalConsumers:
+      - "Developers building documentation portals"
+      - "Teams creating schema registries"
+    notes: "MUST comply with CDRL standard. REQUIRED: .fulmen/app.yaml, CDRL validation targets, fulmen_cdrl_guide.md. Astro/Starlight baseline."
+    references:
+      - "docs/architecture/fulmen-forge-codex-standard.md"
+      - "docs/architecture/fulmen-template-cdrl-standard.md"
+      - "docs/standards/cdrl/workflow-guide.md"
+      - "docs/standards/makefile-standard.md#annex-b-template-repository-cdrl-targets"
+  - key: forge-gymnasium
+    summary: "Experimental templates for prototyping and research (CDRL optional until graduation)"
+    primaryEntryPoints:
+      - "Template repository (GitHub)"
+      - "Experimental workflows"
+    typicalConsumers:
+      - "Researchers"
+      - "Prototype developers"
+    notes: "Experimental template category. May graduate to forge-workhorse or forge-codex upon maturity. CDRL compliance RECOMMENDED but not required until stable."
+    references:
+      - "docs/architecture/fulmen-template-cdrl-standard.md"